`load_vectors`

Use the load vectors operation to load vector data from a CSV file in cloud storage into an existing vector table.

The operation appends vector records from cloud storage into an existing vector table. The table must already exist. For integrated embedding tables, the table’s embed_params configuration is used to generate embeddings when needed.

Performance consideration: When source records do not contain precomputed vectors, embedding is performed as part of the load job using database CPU resources. This can make integrated embedding loads slower than loading precomputed vectors and can increase database CPU utilization during the job.

Parameters

Parameter	Type	Value Range	Required	Default	Description	Notes
`table_name`	`str`	Valid vector table identifier	Yes	No default	Name of the target vector table for the load job.	The table must already exist. New vectors are appended to it.
`url`	`str`	Cloud URI or public URL	Yes	No default	Object storage URL pointing to the CSV file containing vectors.	The file is loaded through the database cloud loader.
`params`	`dict`	Object or NULL	No	None	Optional load settings.	Supports `credential`.
`debug_flags`	`dict`	Object or NULL	No	None	Debug or tracing flags for detailed logging.	Optional; omit unless diagnostics are needed.

params fields

Field	Type	Value Range	Required	Description	Notes
`credential`	`str`	Valid string	No	Database credential used when the object storage URL requires authentication. Refer to the Oracle Cloud Infrastructure documentation for configuring object storage credentials: Managing Credentials.	Required only for private or protected object storage URLs.

Guidelines for Preparing CSV Files for load_vectors

General Structure

The file must be a valid comma-separated values (CSV) file.
The first row must define the column names.
Each field must be separated by a comma (,).

Handling Fields with Commas

If a dense vector or metadata field contains commas, enclose the entire field in double quotation marks ("). This ensures that the CSV parser treats the value as a single column.

Embedding JSON in CSV

If these guidelines are not followed, the CSV parser can incorrectly split fields and cause ingestion errors.

JSON fields must use double quotation marks (") for all property names and string values.
To include double quotation marks inside JSON within a CSV field, escape them by doubling ("").
Do not use apostrophes in JSON.
Always enclose JSON content in double quotation marks.

Example:

id,metadata
77E0D7F0-1942-494A-ACE2-9004D2BDC59E,"{""PARK_CODE"":""abli"",""NAME"":""Abraham Lincoln Birthplace"",""STATES"":""KY""}"

Header Row Formats

For integrated embedding vector tables, use one of the following header row formats:

ID, METADATA
METADATA, if table_params.auto_generate_id is set to true

For bring-your-own-vector tables, use one of the following header row formats:

ID, DENSE_VECTOR
ID, DENSE_VECTOR, METADATA
METADATA, if table_params.auto_generate_id is set to true
DENSE_VECTOR, if table_params.auto_generate_id is set to true

The order of columns is flexible. Headers are not case-sensitive.

ID Field Guidelines

If table_params.auto_generate_id is set to false, each row must include a unique ID in the appropriate column.
If table_params.auto_generate_id is set to true, the ID column is optional.

For integrated embedding tables, metadata must include the text path configured by embed_params.embed_metadata_jsonpath. For example, if embed_metadata_jsonpath is description, then each metadata object must contain a description text value. Use a JSON path, such as details.summary, to embed text from nested metadata.

Raises InvalidTableNameFormatError is raised when the table name is invalid.

Load vectors from object storage

load_job = client.load_vectors(
    table_name='products',
    url='https://objectstorage.region.oraclecloud.com/.../vectors.csv',
    params={'credential': 'OCI_CREDENTIAL'}
)

Check load status and retrieve a failure log

Use the job name returned by load_vectors() to inspect the load status and retrieve diagnostics for a failed job.

job_status = client.describe_vector_load_job(
    load_job_name=load_job.job_name
)
print(job_status.to_dict())

if job_status.state == "FAILED":
    job_log = client.get_vector_load_job_log(
        load_job_name=load_job.job_name
    )
    print(job_log.to_dict())

Return type JobResponse

Returns JSON response containing the load job ID and initial status.

Example response:

{
    "job_name": "VECDB_LOAD_ABC123",
    "job_creator": "VECTOR3",
    "operation": "LOAD",
    "state": "SUCCEEDED",
    "links": [
        {
            "rel": "collection",
            "href": "https://<host>/ords/<schema>/_/db-api/stable/vecdb/load/jobs/"
        },
        {
            "rel": "self",
            "href": "https://<host>/ords/<schema>/_/db-api/stable/vecdb/load/jobs/vecdb_load_abc123/"
        },
        {
            "rel": "related",
            "href": "https://<host>/ords/<schema>/_/db-api/stable/vecdb/load/jobs/vecdb_load_abc123/jobfile"
        }
    ]
}