files

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

Overview

Name	files
Type	Resource
Id	openai.vector_stores.files

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.
attributes	object	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. (x-oaiTypeLabel: map)
chunking_strategy	object	The strategy used to chunk the file. (title: Static Chunking Strategy)
created_at	integer (unixtime)	The Unix timestamp (in seconds) for when the vector store file was created.
last_error	object	The last error associated with this vector store file. Will be null if there are no errors.
object	string	The object type, which is always vector_store.file. (vector_store.file)
status	string	The status of the vector store file, which can be either in_progress, completed, cancelled, or failed. The status completed indicates that the vector store file is ready for use. (in_progress, completed, cancelled, failed)
usage_bytes	integer	The total vector store usage in bytes. Note that this may be different from the original file size.

list

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.
attributes	object	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. (x-oaiTypeLabel: map)
chunking_strategy	object	The strategy used to chunk the file. (title: Static Chunking Strategy)
created_at	integer (unixtime)	The Unix timestamp (in seconds) for when the vector store file was created.
last_error	object	The last error associated with this vector store file. Will be null if there are no errors.
object	string	The object type, which is always vector_store.file. (vector_store.file)
status	string	The status of the vector store file, which can be either in_progress, completed, cancelled, or failed. The status completed indicates that the vector store file is ready for use. (in_progress, completed, cancelled, failed)
usage_bytes	integer	The total vector store usage in bytes. Note that this may be different from the original file size.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	vector_store_id, file_id	openai-organization, openai-project
list	select	vector_store_id	limit, order, after, before, filter, openai-organization, openai-project
create	insert	vector_store_id, file_id	openai-organization, openai-project	This endpoint is subject to a per-vector-store write rate limit of 300 requests per minute, shared with /vector_stores/{vector_store_id}/file_batches. For uploading multiple files to the same vector store, use the file batches endpoint to reduce request volume.
update	update	vector_store_id, file_id, attributes	openai-organization, openai-project
delete	delete	vector_store_id, file_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
file_id	string	The ID of the file to delete.
vector_store_id	string	The ID of the vector store that the file belongs to.
after	string	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	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	string	Filter by file status. One of in_progress, completed, failed, cancelled.
limit	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. Automatically applied from a SQL LIMIT clause - SELECT ... LIMIT 10 sends limit=10 on the wire. Setting it explicitly in a WHERE clause is not required.
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.
order	string	Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

SELECT examples

get

OK

SELECT
id,
vector_store_id,
attributes,
chunking_strategy,
created_at,
last_error,
object,
status,
usage_bytes
FROM openai.vector_stores.files
WHERE vector_store_id = '{{ vector_store_id }}' -- required
AND file_id = '{{ file_id }}' -- required
AND "openai-organization" = '{{ openai-organization }}'
AND "openai-project" = '{{ openai-project }}'
;

list

OK

SELECT
id,
vector_store_id,
attributes,
chunking_strategy,
created_at,
last_error,
object,
status,
usage_bytes
FROM openai.vector_stores.files
WHERE vector_store_id = '{{ vector_store_id }}' -- required
AND "order" = '{{ order }}'
AND after = '{{ after }}'
AND before = '{{ before }}'
AND filter = '{{ filter }}'
AND "openai-organization" = '{{ openai-organization }}'
AND "openai-project" = '{{ openai-project }}'
;

INSERT examples

create

This endpoint is subject to a per-vector-store write rate limit of 300 requests per minute, shared with /vector_stores/{vector_store_id}/file_batches.
For uploading multiple files to the same vector store, use the file batches endpoint to reduce request volume.

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

Manifest

# Description fields are for documentation purposes
- name: files
props:
  - name: vector_store_id
    value: "{{ vector_store_id }}"
    description: Required parameter for the files resource.
  - name: file_id
    value: "{{ file_id }}"
    description: |
      A [File](https://platform.openai.com/docs/api-reference/files) ID that the vector store should use. Useful for tools like `file_search` that can access files. For multi-file ingestion, we recommend [`file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch) to minimize per-vector-store write requests.
  - 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`.

UPDATE examples

update

No description available.

UPDATE openai.vector_stores.files
SET 
attributes = '{{ attributes }}'
WHERE 
vector_store_id = '{{ vector_store_id }}' --required
AND file_id = '{{ file_id }}' --required
AND attributes = '{{ attributes }}' --required
AND "openai-organization" = '{{ openai-organization}}'
AND "openai-project" = '{{ openai-project}}'
RETURNING
id,
vector_store_id,
attributes,
chunking_strategy,
created_at,
last_error,
object,
status,
usage_bytes;

DELETE examples

delete

No description available.

DELETE FROM openai.vector_stores.files
WHERE vector_store_id = '{{ vector_store_id }}' --required
AND file_id = '{{ file_id }}' --required
AND "openai-organization" = '{{ openai-organization }}'
AND "openai-project" = '{{ openai-project }}'
;