Load Data Sets

Use the load vectors operation to perform bulk loads of vectors from a CSV file in Oracle Object Storage.

The operation appends vector records from Oracle Object Storage into an existing vector table asynchronously. The table must already exist. For integrated embedding tables, the table's embed_params configuration is used to generate embeddings when needed.

The object storage URL provided as a parameter should point to a CSV file with the following format:

id,dense_vector,metadata
id1,[0.1, 0.2, 0.3],{"field1": "value1", "field2": "value2"}
id2,[0.4, 0.5, 0.6],{"field1": "value3", "field2": "value4"}

Guidelines for preparing CSV files for loading data set:

• General Structure

  • The file should be a valid, comma-separated values (CSV) file.
  • Every file should begin with a header row that defines column names.
  • Each field should be separated by a comma (,).

• Handling Fields with Commas

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

• Embedding JSON in CSV: If the following guidelines are not followed, the CSV parser may incorrectly split fields, resulting in ingestion errors.

  • JSON fields should use double quotes (") for all property names and string values.
  • To include double quotes inside JSON within a CSV field, escape them by doubling: ("").
  • Do not use single quotes (') in JSON.
  • Always enclose JSON content in double quotes ("").

  • JSON example:

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

• Header Row Formats

  • For embedded model table:
    • ID, METADATA )
    • METADATA ( if auto_generated_id is set to True
  • For bring your own vector table:
    • ID, DENSE_VECTOR
    • ID,DENSE_VECTOR, METADATA
    • METADATA ( if auto_generated_id is set to True)
    • DENSE_VECTOR ( if auto_generated_id is set to True)
  • The order of columns is flexible.
  • Headers are not case-sensitive (for example: METADATA, Metadata, or "Metadata" are all valid).

• ID Field Guidelines

  • If auto_generated_id is set to False, each data row should include a unique ID in the appropriate column.
  • If auto_generated_id is set to True, providing the ID column is optional.

A JSON response is returned containing the load job ID and initial status.

• Python
• Curl
• PL/SQL

See the following for an example of bulk loading vectors from Oracle Object Storage and monitoring the load process.

First load vectors from object storage into a variable called response, then use describe_vector_load_job to monitor the load process:

from oracle_vecdb import OracleVecDB, Configuration

client = OracleVecDB(Configuration(
    rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
    access_token="<bearer-token>", # or username="<user>", password="<pass>"
))

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

import json
job = json.loads(response)
status = client.describe_vector_load_job(job['job_name'])

print(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"
    }
  ]
}

For more information about the load_vectors operation, see Python API Reference.

See how POST /vecdb/load can be used in the following example:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/load" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  # Choose ONE authentication method:

  # Option 1: Basic authentication
  -u "<user>:<password>" \

  # Option 2: OAuth Bearer token
  # -H "Authorization: Bearer <access_token>" \

  -d '{
    "tableName": "product_vectors",
    "url": "https://objectstorage.example.com/data/product_vectors.csv",
    "params": {
      "credential": "OBJ_STORE_CRED"
    }
  }'

Responses:

• Example 200 response:

  {
    "job_creator": "APPUSER",
    "job_name": "VECDB_LOAD_20260501110000",
    "job_type": "PLSQL_BLOCK",
    "operation": "LOAD",
    "state": "SCHEDULED",
    "start_date": "2026-05-01T11:00:00.118886Z",
    "links": [
      {
        "href": "/vecdb/load/jobs/",
        "rel": "collection"
      },
      {
        "href": "/vecdb/load/jobs/vecdb_load_20260501110000/",
        "rel": "self"
      },
      {
        "href": "/vecdb/load/jobs/vecdb_load_20260501110000/jobfile",
        "rel": "related"
      }
    ]
  }

• 400 - the request body included invalid parameters.

For more information about POST /vecdb/load, see REST API Reference.

See how DBMS_VECTOR_DATABASE.LOAD_VECTORS can be used in the following example:

dbms_vector_database.load_vectors(
    table_name => 'product_vectors',
    url => 'https://objectstorage.example.com/data/product_vectors.csv',
    params => JSON('{"credential": "OBJ_STORE_CRED"}')
);

Example response:

{
  "table_name": "PRODUCT_VECTORS",
  "file_url": "https://objectstorage.example.com/data/product_vectors.csv"
}

For more information about the PL/SQL implementation, including parameters, see LOAD_VECTORS.