file_batches

Creates, updates, deletes, gets or lists a file_batches resource.

Overview

Name	file_batches
Type	Resource
Id	openai.vector_stores.file_batches

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	The identifier, which can be referenced in API endpoints.
vector_store_id	string	The ID of the vector store that the File is attached to.
created_at	integer (unixtime)	The Unix timestamp (in seconds) for when the vector store files batch was created.
file_counts	object
object	string	The object type, which is always vector_store.file_batch. (vector_store.files_batch)
status	string	The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed. (in_progress, completed, cancelled, failed)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	vector_store_id, batch_id	openai-organization, openai-project
create	insert	vector_store_id, file_ids, files	openai-organization, openai-project	The maximum number of files in a single batch request is 2000. Vector store file attach requests are rate limited per vector store (300 requests per minute across both this endpoint and /vector_stores/{vector_store_id}/files). For ingesting multiple files into the same vector store, this batch endpoint is recommended.
cancel	exec	vector_store_id, batch_id	openai-organization, openai-project

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
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.
openai-organization	string	Optionally scope the request to a specific organization (overrides the default associated with the API key). Addressable in SQL as openai_organization.
openai-project	string	Optionally scope the request to a specific project (overrides the default associated with the API key). Addressable in SQL as openai_project.

SELECT examples

get

OK

SELECT
id,
vector_store_id,
created_at,
file_counts,
object,
status
FROM openai.vector_stores.file_batches
WHERE vector_store_id = '{{ vector_store_id }}' -- required
AND batch_id = '{{ batch_id }}' -- required
AND "openai-organization" = '{{ openai-organization }}'
AND "openai-project" = '{{ openai-project }}'
;

INSERT examples

create

The maximum number of files in a single batch request is 2000.
Vector store file attach requests are rate limited per vector store (300 requests per minute across both this endpoint and /vector_stores/{vector_store_id}/files).
For ingesting multiple files into the same vector store, this batch endpoint is recommended.

INSERT INTO openai.vector_stores.file_batches (
file_ids,
files,
chunking_strategy,
attributes,
vector_store_id,
"openai-organization",
"openai-project"
)
SELECT 
'{{ file_ids }}' /* required */,
'{{ files }}' /* required */,
'{{ chunking_strategy }}',
'{{ attributes }}',
'{{ vector_store_id }}',
'{{ openai-organization }}',
'{{ openai-project }}'
RETURNING
id,
vector_store_id,
created_at,
file_counts,
object,
status
;

Manifest

# Description fields are for documentation purposes
- name: file_batches
props:
  - name: vector_store_id
    value: "{{ vector_store_id }}"
    description: Required parameter for the file_batches resource.
  - name: file_ids
    value:
      - "{{ file_ids }}"
    description: |
      A list of [File](https://platform.openai.com/docs/api-reference/files) 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`.
  - name: files
    description: |
      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`.
    value:
      - file_id: "{{ file_id }}"
        chunking_strategy:
          type: "{{ type }}"
          static:
            max_chunk_size_tokens: {{ max_chunk_size_tokens }}
            chunk_overlap_tokens: {{ chunk_overlap_tokens }}
        attributes: "{{ attributes }}"
  - name: chunking_strategy
    description: |
      The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy.
    value:
      type: "{{ type }}"
      static:
        max_chunk_size_tokens: {{ max_chunk_size_tokens }}
        chunk_overlap_tokens: {{ chunk_overlap_tokens }}
  - name: attributes
    value: "{{ attributes }}"
    description: |
      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.
  - name: openai-organization
    value: "{{ openai-organization }}"
    description: Optionally scope the request to a specific organization (overrides the default associated with the API key). Addressable in SQL as `openai_organization`.
    description: Optionally scope the request to a specific organization (overrides the default associated with the API key). Addressable in SQL as `openai_organization`.
  - name: openai-project
    value: "{{ openai-project }}"
    description: Optionally scope the request to a specific project (overrides the default associated with the API key). Addressable in SQL as `openai_project`.
    description: Optionally scope the request to a specific project (overrides the default associated with the API key). Addressable in SQL as `openai_project`.

Lifecycle Methods

cancel

OK

EXEC openai.vector_stores.file_batches.cancel 
@vector_store_id='{{ vector_store_id }}' --required, 
@batch_id='{{ batch_id }}' --required, 
@openai-organization='{{ openai-organization }}', 
@openai-project='{{ openai-project }}'
;