Class: OpenAI::Resources::VectorStores::FileBatches

Inherits:
Object
  • Object
show all
Defined in:
lib/openai/resources/vector_stores/file_batches.rb,
sig/openai/resources/vector_stores/file_batches.rbs

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ FileBatches

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of FileBatches.

Parameters:



363
364
365
 
# File 'lib/openai/resources/vector_stores/file_batches.rb', line 363

def initialize(client:)
  @client = client
end

Instance Method Details

#cancel(batch_id, vector_store_id:, request_options: {}) ⇒ OpenAI::Models::VectorStores::VectorStoreFileBatch

Cancel a vector store file batch. This attempts to cancel the processing of files in this batch as soon as possible.

Parameters:

  • batch_id (String) —

    The ID of the file batch to cancel.

  • vector_store_id (String) —

    The ID of the vector store that the file batch belongs to.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/openai/resources/vector_stores/file_batches.rb', line 169

def cancel(batch_id, params)
  parsed, options = OpenAI::VectorStores::FileBatchCancelParams.dump_request(params)
  vector_store_id = parsed.delete(:vector_store_id) do
    raise ArgumentError.new("missing required path argument #{_1}")
  end

  @client.request(
    method: :post,
    path: ["vector_stores/%1$s/file_batches/%2$s/cancel", vector_store_id, batch_id],
    model: OpenAI::VectorStores::VectorStoreFileBatch,
    security: {bearer_auth: true},
    options: {extra_headers: {"OpenAI-Beta" => "assistants=v2"}, **options}
  )
end

#create(vector_store_id, attributes: nil, chunking_strategy: nil, file_ids: nil, files: nil, request_options: {}) ⇒ OpenAI::Models::VectorStores::VectorStoreFileBatch

Create a vector store file batch.

Parameters:

  • vector_store_id (String) —

    The ID of the vector store for which to create a File Batch.

  • attributes (Hash{Symbol=>String, Float, Boolean}, nil) —

    Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers.

  • chunking_strategy (OpenAI::Models::AutoFileChunkingStrategyParam, OpenAI::Models::StaticFileChunkingStrategyObjectParam) —

    The chunking strategy used to chunk the file(s). If not set, will use the auto strategy. Only applicable if file_ids is non-empty.

  • file_ids (Array<String>) —

    A list of File IDs that the vector store should use. Useful for tools like file_search that can access files. If attributes or chunking_strategy are provided, they will be applied to all files in the batch. The maximum batch size is 2000 files. This endpoint is recommended for multi-file ingestion and helps reduce per-vector-store write request pressure. Mutually exclusive with files.

  • files (Array<OpenAI::Models::VectorStores::FileBatchCreateParams::File>) —

    A list of objects that each include a file_id plus optional attributes or chunking_strategy. Use this when you need to override metadata for specific files. The global attributes or chunking_strategy will be ignored and must be specified for each file. The maximum batch size is 2000 files. This endpoint is recommended for multi-file ingestion and helps reduce per-vector-store write request pressure. Mutually exclusive with file_ids.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/openai/resources/vector_stores/file_batches.rb', line 48

def create(vector_store_id, params = {})
  parsed, options = OpenAI::VectorStores::FileBatchCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["vector_stores/%1$s/file_batches", vector_store_id],
    body: parsed,
    model: OpenAI::VectorStores::VectorStoreFileBatch,
    security: {bearer_auth: true},
    options: {
      **options,
      extra_headers: OpenAI::Internal::Util.normalized_headers(
        {"OpenAI-Beta" => "assistants=v2"},
        options[:extra_headers].to_h
      )
    }
  )
end

#create_and_poll(vector_store_id, attributes: nil, chunking_strategy: nil, file_ids: nil, files: nil, poll_interval: nil, timeout: 1800.0, request_options: {}) ⇒ OpenAI::Models::VectorStores::VectorStoreFileBatch

Create a vector store file batch and wait for processing to finish.

The returned batch may have a failed or cancelled status; callers should inspect its status and file counts. Polling intervals and the overall timeout are in seconds. Finite timeouts include authentication and request replay time and disable transport retries so the deadline remains strict. Set timeout to nil to wait indefinitely and retain configured transport retries.

Parameters:

  • vector_store_id (String) —

    The ID of the vector store for which to create a File Batch.

  • attributes (Hash{Symbol=>String, Float, Boolean}, nil) (defaults to: nil) —

    Attributes to apply to each file in file_ids.

  • chunking_strategy (OpenAI::Models::AutoFileChunkingStrategyParam, OpenAI::Models::StaticFileChunkingStrategyObjectParam) (defaults to: nil) —

    The chunking strategy used to chunk the files.

  • file_ids (Array<String>) (defaults to: nil) —

    File IDs to add to the vector store.

  • files (Array<OpenAI::Models::VectorStores::FileBatchCreateParams::File>) (defaults to: nil) —

    File IDs with per-file attributes or chunking strategies.

  • poll_interval (Integer, Float, nil) (defaults to: nil) —

    How often to retrieve the batch. When omitted, the SDK honors the server's polling hint and otherwise waits 5 seconds.

  • timeout (Integer, Float, nil) (defaults to: OpenAI::Internal::Poller::DEFAULT_TIMEOUT) —

    Maximum total time to poll. Defaults to 30 minutes. Set to nil to wait indefinitely.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil) (defaults to: {})

Returns:

Raises:



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/openai/resources/vector_stores/file_batches.rb', line 96

def create_and_poll(
  vector_store_id,
  attributes: nil,
  chunking_strategy: nil,
  file_ids: nil,
  files: nil,
  poll_interval: nil,
  timeout: OpenAI::Internal::Poller::DEFAULT_TIMEOUT,
  request_options: {}
)
  OpenAI::Internal::Poller.validate!(poll_interval: poll_interval, timeout: timeout)

  params = {request_options: request_options}
  params[:attributes] = attributes unless attributes.nil?
  params[:chunking_strategy] = chunking_strategy unless chunking_strategy.nil?
  params[:file_ids] = file_ids unless file_ids.nil?
  params[:files] = files unless files.nil?
  batch = create(vector_store_id, params)
  poll(
    batch.id,
    vector_store_id: vector_store_id,
    poll_interval: poll_interval,
    timeout: timeout,
    request_options: request_options
  )
end

#list_files(batch_id, vector_store_id:, after: nil, before: nil, filter: nil, limit: nil, order: nil, request_options: {}) ⇒ OpenAI::Internal::CursorPage<OpenAI::Models::VectorStores::VectorStoreFile>

Returns a list of vector store files in a batch.

Parameters:

  • batch_id (String) —

    Path param: The ID of the file batch that the files belong to.

  • vector_store_id (String) —

    Path param: The ID of the vector store that the files belong to.

  • after (String) —

    Query param: A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

  • before (String) —

    Query param: A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

  • filter (Symbol, OpenAI::Models::VectorStores::FileBatchListFilesParams::Filter) —

    Query param: Filter by file status. One of in_progress, completed, failed, cancelled.

  • limit (Integer) —

    Query param: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

  • order (Symbol, OpenAI::Models::VectorStores::FileBatchListFilesParams::Order) —

    Query param: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/openai/resources/vector_stores/file_batches.rb', line 223

def list_files(batch_id, params)
  parsed, options = OpenAI::VectorStores::FileBatchListFilesParams.dump_request(params)
  vector_store_id = parsed.delete(:vector_store_id) do
    raise ArgumentError.new("missing required path argument #{_1}")
  end

  query = OpenAI::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["vector_stores/%1$s/file_batches/%2$s/files", vector_store_id, batch_id],
    query: query,
    page: OpenAI::Internal::CursorPage,
    model: OpenAI::VectorStores::VectorStoreFile,
    security: {bearer_auth: true},
    options: {extra_headers: {"OpenAI-Beta" => "assistants=v2"}, **options}
  )
end

#poll(batch_id, vector_store_id:, poll_interval: nil, timeout: 1800.0, request_options: {}) ⇒ OpenAI::Models::VectorStores::VectorStoreFileBatch

Wait for a vector store file batch to finish processing.

The returned batch may have a failed or cancelled status; callers should inspect its status and file counts. Polling intervals and the overall timeout are in seconds. Set timeout to nil to wait indefinitely.

Parameters:

  • batch_id (String) —

    The ID of the file batch being retrieved.

  • vector_store_id (String) —

    The ID of the vector store that the file batch belongs to.

  • poll_interval (Integer, Float, nil) (defaults to: nil) —

    How often to retrieve the batch. When omitted, the SDK honors the server's polling hint and otherwise waits 5 seconds.

  • timeout (Integer, Float, nil) (defaults to: OpenAI::Internal::Poller::DEFAULT_TIMEOUT) —

    Maximum total time to poll. Defaults to 30 minutes. Set to nil to wait indefinitely.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil) (defaults to: {})

Returns:

Raises:



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/openai/resources/vector_stores/file_batches.rb', line 263

def poll(
  batch_id,
  vector_store_id:,
  poll_interval: nil,
  timeout: OpenAI::Internal::Poller::DEFAULT_TIMEOUT,
  request_options: {}
)
  OpenAI::Helpers::ResourcePolling.poll_vector_store_file_batch(
    self,
    batch_id,
    vector_store_id: vector_store_id,
    poll_interval: poll_interval,
    timeout: timeout,
    request_options: request_options
  )
end

#retrieve(batch_id, vector_store_id:, request_options: {}) ⇒ OpenAI::Models::VectorStores::VectorStoreFileBatch

Retrieves a vector store file batch.

Parameters:

  • batch_id (String) —

    The ID of the file batch being retrieved.

  • vector_store_id (String) —

    The ID of the vector store that the file batch belongs to.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/openai/resources/vector_stores/file_batches.rb', line 138

def retrieve(batch_id, params)
  parsed, options = OpenAI::VectorStores::FileBatchRetrieveParams.dump_request(params)
  vector_store_id = parsed.delete(:vector_store_id) do
    raise ArgumentError.new("missing required path argument #{_1}")
  end

  @client.request(
    method: :get,
    path: ["vector_stores/%1$s/file_batches/%2$s", vector_store_id, batch_id],
    model: OpenAI::VectorStores::VectorStoreFileBatch,
    security: {bearer_auth: true},
    options: {extra_headers: {"OpenAI-Beta" => "assistants=v2"}, **options}
  )
end

#upload_and_poll(vector_store_id, files:, file_ids: [], max_concurrency: 5, attributes: nil, chunking_strategy: nil, poll_interval: nil, timeout: 1800.0, request_options: {}) ⇒ OpenAI::Models::VectorStores::VectorStoreFileBatch

Upload files concurrently, create a vector store file batch, and wait for processing to finish.

Existing file IDs can be included alongside new uploads. Upload concurrency is bounded and defaults to 5. Set max_concurrency to 1 for sequential uploads. Inputs are enumerated before requests begin so the 2,000-file API limit can be checked without orphaning uploads. Stream-backed inputs are safely spooled during enumeration, including IO objects yielded from block-scoped enumerators.

Parameters:

  • vector_store_id (String) —

    The ID of the vector store for which to create a File Batch.

  • files (Enumerable<Pathname, StringIO, IO, String, OpenAI::FilePart>) —

    Files to upload.

  • file_ids (Array<String>) (defaults to: []) —

    IDs of files that have already been uploaded.

  • max_concurrency (Integer) (defaults to: 5) —

    Maximum number of simultaneous file uploads.

  • attributes (Hash{Symbol=>String, Float, Boolean}, nil) (defaults to: nil) —

    Attributes to apply to every file.

  • chunking_strategy (OpenAI::Models::AutoFileChunkingStrategyParam, OpenAI::Models::StaticFileChunkingStrategyObjectParam) (defaults to: nil) —

    The chunking strategy used to chunk the files.

  • poll_interval (Integer, Float, nil) (defaults to: nil) —

    How often to retrieve the batch. When omitted, the SDK honors the server's polling hint and otherwise waits 5 seconds.

  • timeout (Integer, Float, nil) (defaults to: OpenAI::Internal::Poller::DEFAULT_TIMEOUT) —

    Maximum total time to poll. Defaults to 30 minutes. Set to nil to wait indefinitely.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil) (defaults to: {}) —

    Applied to every upload and to the batch creation and polling requests. Idempotency keys are scoped to each upload and the batch creation.

Returns:

Raises:



315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/openai/resources/vector_stores/file_batches.rb', line 315

def upload_and_poll(
  vector_store_id,
  files:,
  file_ids: [],
  max_concurrency: 5,
  attributes: nil,
  chunking_strategy: nil,
  poll_interval: nil,
  timeout: OpenAI::Internal::Poller::DEFAULT_TIMEOUT,
  request_options: {}
)
  OpenAI::Internal::Poller.validate!(poll_interval: poll_interval, timeout: timeout)
  request_options_scope = OpenAI::Internal::RequestOptionsScope.new(request_options)

  max_files = OpenAI::Internal::VectorStoreFileUploader::MAX_FILES_PER_BATCH
  if file_ids.length > max_files
    raise ArgumentError, "`file_ids` cannot contain more than #{max_files} entries"
  end

  uploaded = OpenAI::Internal::VectorStoreFileUploader
    .new(
      client: @client,
      max_concurrency: max_concurrency,
      request_options: request_options
    )
    .upload(files, max_files: max_files - file_ids.length)

  if uploaded.empty?
    raise(
      ArgumentError,
      "No `files` provided. Use `create_and_poll` when all files are already uploaded."
    )
  end

  create_and_poll(
    vector_store_id,
    file_ids: [*file_ids, *uploaded.map(&:id)],
    attributes: attributes,
    chunking_strategy: chunking_strategy,
    poll_interval: poll_interval,
    timeout: timeout,
    request_options: request_options_scope.child("file-batch")
  )
end