DBMS_VECTOR_DATABASE

The DBMS_VECTOR_DATABASE package provides APIs for common Oracle AI Vector Search operations, including vector table management, vector data operations, vector search, index management, and model operations.

These PL/SQL functions accept input parameters in JSON format where noted. The functions return a CLOB that contains the JSON response.

Summary of DBMS_VECTOR_DATABASE Subprograms and Shared Parameter Objects

This table lists the DBMS_VECTOR_DATABASE subprograms and briefly describes them.

Table 1 DBMS_VECTOR_DATABASE Package Subprograms

Subprogram	Description	Impacts
Manage Model: These functions enable you to manage vector embedding model operations.
LOAD_MODEL	Loads an ONNX model from cloud storage into the database.	Adds a model to the current vector user's schema.
LIST_MODELS	Lists mining models available in the caller schema.	None; read-only
DESCRIBE_MODEL	Retrieves details for a model in the caller schema.	None; read-only
DROP_MODEL	Drops an existing model from the caller schema (if not in use by vector tables).	Permanently removes a model from the current vector user's schema.
Manage Vector Tables: These functions enable you to summarize vector database objects and manage vector tables in Oracle AI Database.
SUMMARY	Retrieves summary counts for vector tables, vectors, and models in the caller schema.	None; read-only
CREATE_VECTOR_TABLE	Creates a new vector table.	Creates database objects and managed metadata; commits automatically.
LIST_VECTOR_TABLES	Lists vector tables available in the caller schema.	None; read-only
DESCRIBE_VECTOR_TABLE	Retrieves metadata information about a vector table.	None; read-only
UPDATE_VECTOR_TABLE_ANNOTATION	Updates vector table public comment and annotations.	Replaces the table comment and complete annotations JSON; annotations are not merged. Commits automatically.
DROP_VECTOR_TABLE	Drops an existing vector table.	Permanently deletes the table, its data, indexes, and managed metadata; commits automatically.
Manage Data: These functions enable you enable you to generate embeddings, manage vector data, and load vectors.
GENERATE_EMBEDDING	Generates vector embeddings from text.	None; read-only
LIST_VECTORS	Lists existing vectors by ID or with pagination from a specified vector table.	None; read-only
LOAD_VECTORS	Bulk loads vector data from a CSV file in cloud storage into an existing vector table.	Imports vectors, may generate embeddings, and refreshes metadata/statistics; commits automatically.
UPSERT_VECTORS	Inserts or updates vectors into a specified vector table.	Inserts or replaces vector records; may generate embeddings; commits automatically.
DELETE_VECTORS	Deletes the existing vectors by ID from a specified vector table.	Permanently deletes vector records and refreshes statistics; commits automatically.
Search Data: These functions enable you to perform similarity search and rerank search results.
SEARCH	Performs similarity search with a query text, query vector, or record ID.	None; read-only
RERANK	Reranks documents against a query.	None; read-only
Manage Indexes: These functions enable you to create, check, rebuild, and drop vector indexes.
CREATE_INDEX	Creates or updates vector and metadata indexes for a specified vector table.	Creates indexes and updates managed index metadata; commits automatically.
INDEX_BUILD_STATUS	Retrieves vector index build status for a vector table.	None; read-only
REBUILD_INDEX	Rebuilds vector and metadata indexes for a vector table.	Rebuilds indexes; may affect query performance while running; commits automatically
DROP_INDEX	Drops an existing vector and metadata indexes.	Removes indexes and updates managed index metadata; commits automatically.

This table lists the shared parameter objects DBMS_VECTOR_DATABASE subprograms use and briefly describes them.

These shared object definitions support PL/SQL JSON parameters that accept nested configuration objects.

Table 2 Shared Parameter Objects

Shared Parameter Object	Description
table_params	Defines table creation options
embed_params	Defines how the database generates embeddings automatically from metadata content
index_params	Defines how vector and metadata indexes are created and managed
vector_index_params	Controls vector index configuration
metadata_index_params	Controls how metadata JSON paths are indexed and maintained for metadata filtering
advanced_params	Controls vector index tuning

CREATE_INDEX

Use the DBMS_VECTOR_DATABASE.CREATE_INDEX PL/SQL function to create or update vector and metadata indexes for a vector table.

Purpose

Use this function to create vector indexes, metadata indexes, or both for an existing vector table. Pass nested index_params to control vector index settings and metadata path indexing.

Impacts

This function runs synchronously and can take time to complete, depending on the table size and index configuration.

Syntax

DBMS_VECTOR_DATABASE.CREATE_INDEX (
    table_name                  IN VARCHAR2,
    index_params                IN JSON DEFAULT NULL,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
table_name	VARCHAR2	Existing vector table	Yes	Name of the table on which to create the index	Must exist in caller schema.
index_params	JSON	Object or NULL	No	Vector and metadata index configuration.	Defaults are applied when omitted.
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.create_index(
    table_name => 'product_vectors',
    index_params => JSON('{
      "vector_index_params": {
        "auto_index": true,
        "organization": "INMEMORY GRAPH",
        "distance_metric": "COSINE",
        "accuracy": 95,
        "quantization_type": "SCALAR",
        "compression_ratio": 4,
        "advanced_params": {
          "neighbors": 32,
          "efConstruction": 128,
          "rescore_factor": 4,
          "algorithm": "uniform_quantization"
        }
      },
      "metadata_index_params": {
        "auto_index": true,
        "include_paths": ["category", "price"]
      },
      "parallel_creation": 2
    }')
);

Example response

{
  "message": "Vector index VECIDX_PRODUCT_VECTORS_20260501T100000 and Metadata index(es) for paths [category, price] created successfully for table PRODUCT_VECTORS"
}

CREATE_VECTOR_TABLE

Use the DBMS_VECTOR_DATABASE.CREATE_VECTOR_TABLE PL/SQL function to create a vector table.

Purpose

Use this function to create either a bring-your-own-vector table or a model-backed table. If embed_params is omitted, callers provide vector values directly. If embed_params is supplied, the database uses the configured model and metadata path for text embedding workflows.

Syntax

DBMS_VECTOR_DATABASE.CREATE_VECTOR_TABLE (
    name                        IN VARCHAR2,
    comment                     IN VARCHAR2 DEFAULT NULL,
    annotations                 IN JSON DEFAULT NULL,
    table_params                IN JSON DEFAULT NULL,
    embed_params                IN JSON DEFAULT NULL,
    index_params                IN JSON DEFAULT NULL,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
name	VARCHAR2	Valid table identifier	Yes	Name of the table to create	The table must not already exist in the caller schema.
comment	VARCHAR2	String or NULL	No	Optional table comment	Returned ascomment in table metadata
annotations	JSON	Object or NULL	No	User annotations stored with table metadata	Must be valid JSON
table_params	JSON	Object or NULL	No	Table creation options	Currently supports auto_generate_id
embed_params	JSON	Object or NULL	No	Embedding model configuration for model-backed tables	Supply when the table should generate vectors from metadata text by using a loaded embedding model. Omit for bring-your-own-vector tables.
index_params	JSON	Object or NULL	No	Vector and metadata index configuration	Defaults are applied when omitted
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.create_vector_table(
    name => 'product_vectors',
    comment => 'Product catalog embeddings',
    table_params => JSON('{"auto_generate_id": false}'),
    annotations => JSON('{"domain": "retail"}'),
    index_params => JSON('{
      "vector_index_params": {
        "auto_index": true,
        "organization": "PARTITIONS",
        "distance_metric": "COSINE",
        "accuracy": 90
      },
      "metadata_index_params": {
        "auto_index": true,
        "include_paths": ["category", "price"]
      },
      "parallel_creation": 2
    }')
);

Example Response

{
  "table_name": "PRODUCT_VECTORS",
  "comment": "Product catalog embeddings",
  "table_params": {
    "auto_generate_id": false
  },
  "annotations": {
    "domain": "retail"
  },
  "vector_type": "dense",
  "vector_table_type": "BYOV",
  "embed_params": null,
  "index_params": {
    "vector_index_params": {
      "auto_index": true,
      "organization": "PARTITIONS",
      "distance_metric": "COSINE",
      "accuracy": 90
    },
    "metadata_index_params": {
      "auto_index": true,
      "include_paths": ["category", "price"]
    },
    "parallel_creation": 2
  },
  "owner": "APPUSER",
  "indexes": [],
  "status": "Empty",
  "stats": {
    "total_vectors": 0
  },
  "created": "2026-05-01T10:00:00.000000+00:00",
  "updated": "2026-05-01T10:00:00.000000+00:00"
}

DESCRIBE_MODEL

Use the DBMS_VECTOR_DATABASE.DESCRIBE_MODEL PL/SQL function to retrieve model details in the caller schema.

Purpose

Use this function to retrieve model name, algorithm, mining function, creation date, and model attributes for a single model.

Syntax

DBMS_VECTOR_DATABASE.DESCRIBE_MODEL (
    model_name                  IN VARCHAR2,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
model_name	VARCHAR2	Existing model	Yes	Name of the model to describe	Must exist in caller schema
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.describe_model('DOC_EMBED_MODEL');

Example Response

{
  "model_name": "DOC_EMBED_MODEL",
  "algorithm": "ONNX",
  "mining_function": "EMBEDDING",
  "creation_date": "2026-05-01T10:00:00.000000+00:00",
  "attributes": [
    {
      "name": "DATA",
      "value": "TEXT",
      "data_type": "VARCHAR2",
      "data_length": 4000,
      "vector_info": null
    }
  ]
}

DESCRIBE_VECTOR_TABLE

Use the DBMS_VECTOR_DATABASE.DESCRIBE_VECTOR_TABLE PL/SQL function to retrieve metadata of a vector table.

Purpose

Use this function to inspect the public metadata of a vector table, including table creation parameters, embedding configuration, index configuration, status, statistics, and timestamps.

Syntax

DBMS_VECTOR_DATABASE.DESCRIBE_VECTOR_TABLE (
    name                        IN VARCHAR2,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
name	VARCHAR2	Existing vector table	Yes	Name of the table describe	Must exist in caller schema
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.describe_vector_table('product_vectors');

Example Response

{
  "table_name": "PRODUCT_VECTORS",
  "comment": "Product catalog embeddings",
  "table_params": {
    "auto_generate_id": false
  },
  "annotations": {
    "domain": "retail"
  },
  "vector_type": "dense",
  "vector_table_type": "BYOV",
  "embed_params": null,
  "index_params": {
    "vector_index_params": {
      "auto_index": true,
      "organization": "PARTITIONS",
      "distance_metric": "COSINE"
    },
    "metadata_index_params": {
      "auto_index": true
    },
    "parallel_creation": 1
  },
  "owner": "APPUSER",
  "indexes": [],
  "status": "Empty",
  "stats": {
    "total_vectors": 0
  },
  "created": "2026-05-01T10:00:00.000000+00:00",
  "updated": "2026-05-01T10:00:00.000000+00:00"
}

DELETE_VECTORS

Use the DBMS_VECTOR_DATABASE.DELETE_VECTORS PL/SQL function to delete existing vectors by ID from a specified table.

Purpose

Use this function to remove unwanted vectors from a specified table. This function automatically commits deletions after execution, and changes cannot be rolled back as part of the main transaction.

Impacts

Permanently deletes the specified vector records, refreshes related statistics, and commits the changes automatically. The deletion cannot be rolled back as part of the current transaction.

Syntax

DBMS_VECTOR_DATABASE.DELETE_VECTORS (
    table_name                  IN VARCHAR2,
    ids                         IN JSON,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
table_name	VARCHAR2	Existing vector table	Yes	Name of the target table to delete vectors from	Must exist in caller schema
ids	JSON	Array of strings	Yes	JSON array of IDs to delete	Use explicit ID arrays
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.delete_vectors('myvectors', JSON('["vec1", "vec2"]'));

Example Response

{
  "message": "Deleted 2 rows successfully"
}

DROP_INDEX

Use the DBMS_VECTOR_DATABASE.DROP_INDEX PL/SQL function to drop vector and metadata indexes from a vector table.

Purpose

Use this function to drop the vector index, metadata indexes, or both. The optional index_params.index_type field controls the target scope.

Syntax

 DBMS_VECTOR_DATABASE.DROP_INDEX (
    table_name                  IN VARCHAR2,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL,
    index_params                IN JSON DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
table_name	VARCHAR2	Existing vector table	Yes	Name of the table to remove the index from	Must exist in caller schema
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional
index_params	JSON	Object or NULL	No	Drop scope and metadata path selection	Supportsindex_type, metadata_index_params.include_paths, and metadata_index_params.exclude_paths

  <div class="infoboxnote" markdown="1">

  **Note:**

  - `index_params.index_type` accepts` vector`, `metadata`, or `all`.

  - `vector_index_params` is not supported for `DROP_INDEX`. Use`index_type` to select vector index removal.

  - `metadata_index_params.auto_index` is also not supported for `DROP_INDEX`.

  </div>

Example

DBMS_VECTOR_DATABASE.DROP_INDEX(
    table_name => 'product_vectors',
    index_params => JSON('{
      "index_type": "metadata",
      "metadata_index_params": {
        "include_paths": ["category", "price"]
      }
    }')
);

Example Response

{
  "message": "MVI index(es) for paths [category, price] dropped successfully from table PRODUCT_VECTORS"
}

DROP_MODEL

Use the DBMS_VECTOR_DATABASE.DROP_MODEL PL/SQL function to drop a model from the caller schema.

Purpose

Use this function to remove a model from the database. Dropping a model can affect model-backed vector tables or work flows that depend on it.

Syntax

DBMS_VECTOR_DATABASE.DROP_MODEL (
    model_name                  IN VARCHAR2,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
model_name	VARCHAR2	Existing model	Yes	Name of the model to drop	Must exist in caller schema and must not be referenced by a model-backed vector table.
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.drop_model('DOC_EMBED_MODEL');

Example Response

{
  "message": "Model DOC_EMBED_MODEL dropped successfully"
}

DROP_VECTOR_TABLE

Use the DBMS_VECTOR_DATABASE.DROP_VECTOR_TABLE PL/SQL function to drop an existing vector table.

Purpose

Use this function to delete a vector table and its associated metadata and indexes. This is a destructive operation.

Syntax

 DBMS_VECTOR_DATABASE.DROP_VECTOR_TABLE (
    name                        IN VARCHAR2,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
name	VARCHAR2	Existing vector table	Yes	Name of the table to drop	Must exist in caller schema
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.drop_vector_table('product_vectors');

Example Response

{
  "message": "Table PRODUCT_VECTORS deleted successfully"
}

GENERATE_EMBEDDING

Use the DBMS_VECTOR_DATABASE.GENERATE_EMBEDDING PL/SQL function to generate vector embeddings from text.

Purpose

Use this function to generate embeddings for a JSON array of input text objects using a database embedding model.

Syntax

DBMS_VECTOR_DATABASE.GENERATE_EMBEDDING (
    model_name                  IN VARCHAR2,
    inputs                      IN SYS.JSON_ARRAY_T,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
model_name	VARCHAR2	Existing model	Yes	Embedding model name to generate vector embeddings	Must exist in caller schema
inputs	SYS.JSON_ARRAY_T	Array of objects	Yes	Input text objects	Each object must include text
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

DBMS_VECTOR_DATABASE.GENERATE_EMBEDDING(
    model_name => 'DOC_EMBED_MODEL',
    inputs => SYS.JSON_ARRAY_T('[{"text": "hello world"}]')
);

Example Response

{
  "data": [
    {
      "text": "hello world",
      "embedding": [

0.0117027815,
        0.00419755466,
        -0.0301191173,
        0.011317092
      ]
    }
  ]
}

INDEX_BUILD_STATUS

Use the DBMS_VECTOR_DATABASE.INDEX_BUILD_STATUS PL/SQL function to retrieve vector index build status for a vector table.

Purpose

Use this function to monitor the build or rebuild status of the vector index associated with a vector table.

Syntax

DBMS_VECTOR_DATABASE.INDEX_BUILD_STATUS (
    table_name                  IN VARCHAR2,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
table_name	VARCHAR2	Existing vector table	Yes	Name of the table associated with the vector index which is to monitored for build or rebuild status updates	Must exist in caller schema
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.index_build_status('product_vectors');

Response

{
  "Index Status": "Index build in progress...\nCurrent progress: 75%"
}

LIST_MODELS

Use the DBMS_VECTOR_DATABASE.LIST_MODELS PL/SQL function to list mining models available in the caller schema.

Purpose

Use this function to retrieve model metadata, including model name, algorithm, mining function, creation date, and model attributes.

Syntax

DBMS_VECTOR_DATABASE.LIST_MODELS (
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

DBMS_VECTOR_DATABASE.LIST_MODELS();

Response

{
  "models": [
    {
      "model_name": "DOC_EMBED_MODEL",
      "algorithm": "ONNX",
      "mining_function": "EMBEDDING",
      "creation_date": "2026-05-01T10:00:00.000000+00:00",
      "attributes": [
        {
          "name": "DATA",
          "value": "TEXT",
          "data_type": "VARCHAR2",
          "data_length": 4000,
          "vector_info": null
        }
      ]
    }
  ]
}

LIST_VECTORS

Use the DBMS_VECTOR_DATABASE.LIST_VECTORS PL/SQL function to list existing vectors by ID or with pagination.

Purpose

Use this function to list vector IDs from a specified table.

Syntax

DBMS_VECTOR_DATABASE.LIST_VECTORS (
    table_name                  IN VARCHAR2,
    ids                         IN JSON DEFAULT NULL,
    limit                       IN NUMBER DEFAULT 15,
    offset                      IN NUMBER DEFAULT NULL,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
table_name	VARCHAR2	Existing vector table	Yes	Name of the table to read vectors from	Must exist in caller schema
ids	JSON	Array of strings	No	Optional list of vector IDs to retrieve. Example: ["id1", "id2", "id3"].	Builds an ID filter when provided
limit	NUMBER	> 0	No	Max rows returned	Defaults to 15
offset	NUMBER	>= 0 or NULL	No	Rows to skip	Null is returned as 0
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

DBMS_VECTOR_DATABASE.LIST_VECTORS(
    table_name => 'sample_table',
    ids => JSON('["id1", "id2"]')
);

Example Response

{
  "items": [
    {
      "id": "id1",
      "dense_vector": [0.1, 0.5, 0.4, 0.56],
      "metadata": {
        "product_name": "Noise Cancelling Headphones",
        "category": "electronics",
        "brand": "Sony",
        "price": 299.99
      }
    },
    {
      "id": "id2",
      "dense_vector": [0.14, 0.534, 0.12, 0.58],
      "metadata": {
        "product_name": "Studio Monitor Headphones",
        "category": "electronics",
        "brand": "Audio-Technica",
        "price": 149.99
      }
    }
  ],
  "limit": 2,
  "offset": 0,
  "count": 2
}

LIST_VECTOR_TABLES

Use the DBMS_VECTOR_DATABASE.LIST_VECTOR_TABLES PL/SQL function to list vector tables available in the caller schema.

Purpose

Use this function to retrieve public metadata for vector tables created by DBMS_VECTOR_DATABASE APIs. The function is read-only and returns an empty vector_tables array when no vector tables exist.

Syntax

DBMS_VECTOR_DATABASE.LIST_VECTOR_TABLES (
    debug_flags      IN JSON DEFAULT NULL,
    request_id       IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameter	Type	Value Range	Required	Description	Notes
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.list_vector_tables();

Example Response

{
  "vector_tables": [
    {
      "table_name": "MYVECTORS",
      "comment": "Product embeddings",
      "table_params": {
        "auto_generate_id": false
      },
      "annotations": {
        "domain": "retail"
      },
      "vector_type": "dense",
      "vector_table_type": "BYOV",
      "embed_params": null,
      "index_params": {
        "vector_index_params": {
          "auto_index": true,
          "organization": "PARTITIONS",
          "distance_metric": "COSINE"
        },
        "metadata_index_params": {
          "auto_index": true
        },
        "parallel_creation": 1
      },
      "owner": "APPUSER",
      "indexes": [],
      "status": "Empty",
      "stats": {
        "total_vectors": 0
      },
      "created": "2026-05-01T10:00:00.000000+00:00",
      "updated": "2026-05-01T10:00:00.000000+00:00"
    }
  ]
}

LOAD_MODEL

Use the DBMS_VECTOR_DATABASE.LOAD_MODEL PL/SQL function to load an ONNX model from cloud storage into the database.

Purpose

Use this function to load a model from a URI. Optional model_params enables to provide the cloud credential name and model metadata. After loading, the function returns the same model detail shape as DESCRIBE_MODEL.

Syntax

DBMS_VECTOR_DATABASE.LOAD_MODEL (
    model_name                  IN VARCHAR2,
    url                         IN VARCHAR2,
    model_params                IN JSON DEFAULT NULL,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
model_name	VARCHAR2	Valid model identifier	Yes	Unique name to assign to the loaded model	Must not already exist in the caller schema
url	VARCHAR2	Object storage URL	Yes	Object storage URL where the model file is located	Provide model_params.credential when the URL requires database cloud credentials
model_params	JSON	Object or NULL	No	Optional model loading settings	Supports credential and metadata
debug_flags	JSON	Object or NULL	No	Debug or tracing flags for detailed logging flags	Optional unless diagnostics are needed
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

model_params fields

Field	Type	Value Range	Required	Description	Notes
credential	String	Valid string	No	Database credential used to access the object storage URL	Required only when the model URL is private. Otherwise, requires authentication
metadata	Object	Object or NULL	No	A JSON description of the metadata describing the model. The metadata at minimum must describe the machine learning function supported by the model. The model’s metadata parameters are described in JSON Metadata Parameters for ONNX Models.	Returned in model metadata when provided by the service

Example

dbms_vector_database.load_model(
    model_name => 'DOC_EMBED_MODEL',
    url => 'https://objectstorage.example.com/models/doc_embed.onnx',
    model_params => JSON('{
      "credential": "OBJ_STORE_CRED",
      "metadata": {
        "function": "embedding"
      }
    }')
);

Example Response

{
  "model_name": "DOC_EMBED_MODEL",
  "algorithm": "ONNX",
  "mining_function": "EMBEDDING",
  "creation_date": "2026-05-01T10:00:00.000000+00:00",
  "attributes": [
    {
      "name": "DATA",
      "value": "TEXT",
      "data_type": "VARCHAR2",
      "data_length": 4000,
      "vector_info": null
    }
  ]
}

LOAD_VECTORS

Use the DBMS_VECTOR_DATABASE.LOAD_VECTORS PL/SQL function to load vector data from a CSV file in cloud storage into an existing vector table.

Purpose

Use this function to append vector records from cloud storage into an existing vector table. The table should exist in the database. For model-backed tables, the table’s embed_params configuration is used to generate embeddings when needed.

To load vector dataset in CSV format, the CSV format should comply with standard CSV conventions described in Guidelines for Preparing CSV Files for LOAD_VECTORS Function

Impacts

This function runs synchronously and can take time to complete, depending on the amount of data to load.

  <div class="infoboxnote" markdown="1">

  **Note:**
  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.
  </div>

Syntax

DBMS_VECTOR_DATABASE.LOAD_VECTORS (
    table_name                  IN VARCHAR2,
    url                         IN VARCHAR2,
    params                      IN JSON DEFAULT NULL,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
table_name	VARCHAR2	Existing vector table	Yes	Target vector table name	Must exist in caller schema
url	VARCHAR2	Cloud URI	Yes	CSV file URI	The file is loaded through the database cloud loader
params	JSON	Object or NULL	No	Optional load settings	Supports credential
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

    {: summary="LOAD_VECTORS parameters DBMS_VECTOR_DATABASE" }

Guidelines for Preparing CSV Files for LOAD_VECTORS Function

• 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) contains commas, enclose the entire field in quotation marks ("). 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 must 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 quotation marks (') in JSON.

  • Always enclose JSON content in double quotation marks ("").

  • JSON example:

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

• Header Row Formats

  • For model-backed vector tables, use one of the following header row formats:

    • ID, METADATA )

    • METADATA, if auto_generated_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 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 table_params.auto_generated_id is set to false, each data row should include a unique ID in the appropriate column.

  • If table_params.auto_generated_id is set to true, providing the ID column is optional.

  For model-backed 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 should contain a description text value. Use a JSON path, such as $.details.summary, to embed text from nested metadata.

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"
}

REBUILD_INDEX

Use the DBMS_VECTOR_DATABASE.REBUILD_INDEX PL/SQL function to rebuild vector and metadata indexes for a vector table.

Purpose

Use this function to rebuild vector indexes, metadata indexes, or both. Pass nested index_params to select and tune the rebuild.

Impacts

This function runs synchronously and can take time to complete, depending on the table size and index configuration.

Syntax

DBMS_VECTOR_DATABASE.REBUILD_INDEX (
    table_name                  IN VARCHAR2,
    index_params                IN JSON DEFAULT NULL,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
table_name	VARCHAR2	Existing vector table	Yes	Name of the table on which to rebuild the index	Must exist in caller schema
index_params	JSON	Object or NULL	No	Rebuild scope and index configuration	metadata_index_params.auto_index is not supported for rebuild
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.rebuild_index(
    table_name => 'product_vectors',
    index_params => JSON('{
      "vector_index_params": {
        "auto_index": true,
        "organization": "INMEMORY GRAPH",
        "distance_metric": "COSINE",
        "advanced_params": {
          "neighbors": 32,
          "efConstruction": 128,
          "rescore_factor": 4
        }
      },
      "parallel_creation": 2
    }')
);

Example Response

{
  "message": "Vector index VECIDX_PRODUCT_VECTORS_20260501T100000 Rebuild successfully for table PRODUCT_VECTORS"
}

RERANK

Use the DBMS_VECTOR_DATABASE.RERANK PL/SQL function to rerank documents against a query.

Purpose

Use this function to rerank candidate documents by relevance to a query using a database rerank model. The function returns the response from DBMS_VECTOR.RERANK.

Syntax

DBMS_VECTOR_DATABASE.RERANK (
    model_name                  IN VARCHAR2,
    query                       IN VARCHAR2,
    documents                   IN JSON,
    model_params                IN JSON DEFAULT NULL,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
model_name	VARCHAR2	Existing model	Yes	Rerank model name	Must exist in caller schema
query	VARCHAR2	Non-empty string	Yes	Query used for reranking	Empty values raise validation error
documents	JSON	Array	Yes	Candidate documents to rerank	Must be a JSON array
model_params	JSON	Object or NULL	No	Rerank options	Supports top_n
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.rerank(
    model_name => 'RERANK_MODEL',
    query => 'good headphone',
    documents => JSON('[
      "Studio Monitor Headphones",
      "Wireless Earbuds",
      "Coffee Grinder"
    ]'),
    model_params => JSON('{"top_n": 2}')
);

Example Response

[
  {
    "index": 0,
    "score":
0.92
  },
  {
    "index": 1,
    "score": 0.76
  }
]

SEARCH

Use the DBMS_VECTOR_DATABASE.SEARCH PL/SQL function to search a vector table using a query vector, text, or record ID.

Purpose

Use this function to perform similarity search and find the most similar vectors in a table. It supports metadata filters and distance metrics. It returns IDs, metadata, vectors, and distance values/scores. For common distance metrics, lower values indicate closer matches. Text search requires an integrated embedding table with embed_params.

Use query_by to search with text, a vector, or an ID. Exactly one query mode must be supplied.

Note: If no vector index exists, search uses an exact base-table or metadata-index route with filters.

Syntax

DBMS_VECTOR_DATABASE.SEARCH (
    table_name                  IN VARCHAR2,
    query_by                    IN JSON,
    filters                     IN JSON DEFAULT NULL,
    top_k                       IN NUMBER,
    include_vectors             IN BOOLEAN DEFAULT FALSE,
    output_selector             IN JSON DEFAULT NULL,
    advanced_options            IN JSON DEFAULT NULL,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
table_name	VARCHAR2	Existing vector table	Yes	Name of the vector table to search	Must exist in caller schema
query_by	JSON	Exactly one query mode	Yes	Query vector source	text, id, orvector
filters	JSON	Object or NULL	No	Metadata filters	Must be a JSON object. When provided; filters are translated by the QBE helper and applied to metadata.
top_k	Number	>0	Yes	Top- k nearest results to return	Zero or negative values raise a validation error.
include_vectors	BOOLEAN	TRUE, FALSE	No	Include result vectors in output	Defaults to FALSE
advanced_options	JSON	Object or NULL	No	Search tuning options	Supports distance_metric, accuracy,idx_parameters, and advanced_params
output_selector	JSON	Array of strings or NULL	No	Top-level metadata keys to project in each result	NULL returns full metadata; an empty array returns an empty metadata object
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

output_selector values

Value	Behavior	Notes
NULL	Returns fullCONTENT_METADATA	Default behavior
Array of strings	Projects selected top-level metadata keys into the resultmetadata object	Example: ['tenant', 'title']
Empty array	Returns an empty metadata object	Results still include id and distance
Dotted string	Treats the value as a literal top-level key	['a.b'] does not navigate nested JSON
Non-string or empty-string entry	Not supported	Use arrays of non-empty strings only

query_by

Exactly one query mode must be supplied

Field	Type	Required	Description	Notes
text	String	One of three	Text query embedded with the table model	Only valid for model-backed tables
id	Scalar	One of three	Uses the stored vector for the ID	Null or non-scalar values raise validation errors
vector	Array of number	One of three	Caller-supplied query vector	Used directly

filters

Search uses QBE translation for filters. The SEARCH signature does not change, but filter validation is handled through the QBE translator

Filter Capability	Notes
Scalar equality	Example: {"tenant":"acme"}
Comparison operators	$eq, $ne, $gt, $gte, $lt, $lte
Membership operators	$in, $nin
Existence	$exists
Logical operators	$and, $or
QBE/spatial operators	Supported through the QBE translator when valid
Invalid filters	Raise -57725 or an invalid search filter error

advanced_options

Field	Type	Required	Description	Notes
distance_metric	String	No	Query-time distance metric	Validation is case-insensitive. For more information, see Vector Distance Metrics
accuracy	Number	No	Query-time trade-off between speed and accuracy	Use a higher value when search quality is more important than speed. For more information, see Understand Approximate Similarity Search Using Vector Indexes
idx_parameters	Object	No	Query-time vector index parameters	Can include efsearch for HNSW and neighbor partition probes for IVF
advanced_params	Object	No	Additional query-time tuning parameters	Supports rescore_factor

idx_parameters fields

Field	Type	Value Range	Required	Description	Notes
efsearch	integer	> 0	No	HNSW beam width that controls recall. Use this value to specify the maximum number of candidates considered while probing the index.	Supported only with HNSW
neighbor partition probes	integer	> 0	No	IVF partition probes. Increasing the number of partitions scanned can improve recall for IVF indexes.	Supported only with IVF
rescore_factor	integer	1-100	No	Controls the number of candidates rescored during search.	Use only when quantization is configured when creating the vector table

Example

dbms_vector_database.search(
    table_name => 'product_vectors',
    query_by => JSON('{"text": "good headphone"}'),
    top_k => 5,
    filters => JSON('{
      "$and": [
        {"category": {"$eq": "electronics"}},
        {"price": {"$lt": 200}}
      ]
    }'),
    output_selector => JSON('["product_name", "price", "product_description"]'),
    include_vectors => FALSE
);

Example Response

{
  "results": [
    {
      "id": "id2",
      "distance": 0.212,
      "metadata": {
        "product_name": "Studio Monitor Headphones",
        "price": 149.99,
        "product_description": "Professional wired headphones with accurate sound for studio use."
      }
    },
    {
      "id": "id5",
      "distance": 0.678,
      "metadata": {
        "product_name": "Wireless Earbuds",
        "price": 199.99,
        "product_description": "Noise-cancelling wireless earbuds with rich sound and secure fit."
      }
    }
  ]
}

When include_vectors is TRUE, each result can also include a vector field.

SUMMARY

Use the DBMS_VECTOR_DATABASE.SUMMARY PL/SQL function to retrieve summary counts for vector tables created by DBMS_VECTOR_DATABASE.CREATE_VECTOR_TABLE, their vectors, and models in the caller schema.

Purpose

Use this function to retrieve a compact summary of vector tables managed by DBMS_VECTOR_DATABASE, their vectors, and models for the current user.

Syntax

DBMS_VECTOR_DATABASE.SUMMARY (
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameter	Type	Value Range	Required	Description	Notes
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.summary()

Example Response

{
  "total_tables": 3,
  "total_vectors": 12500,
  "total_models": 2
}

UPSERT_VECTORS

Use the DBMS_VECTOR_DATABASE.UPSERT_VECTORS PL/SQL function to insert or update vectors in a specified table.

Purpose

Use this function to ingest new vectors, or add metadata, or update existing vectors.

Syntax

DBMS_VECTOR_DATABASE.UPSERT_VECTORS (
    table_name                  IN VARCHAR2,
    vectors                     IN JSON,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
table_name	VARCHAR2	Existing vector table	Yes	Name of the target vector table to ingest the new vectors in	Must exist in caller schema
vectors	JSON	Array of vector record objects	Yes	Rows to insert or update	For bring-your-own-vector tables, include precomputed dense_vector values. For integrated embedding tables, include text in metadata at the configured embedding source field.
debug_flags	JSON	Object or NULL	No	Debug or tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

DBMS_VECTOR_DATABASE.UPSERT_VECTORS(
    'sample_table',
    vectors => JSON('[
      {
        "id": "vec1",
        "dense_vector": [0.1, 0.5, 0.4, 0.56],
        "metadata": {"type": "document", "source": "Wikipedia"}
      },
      {
        "id": "vec2",
        "dense_vector": [0.14, 0.534, 0.12, 0.58],
        "metadata": {"type": "document", "source": "Internal"}
      }
    ]')
);

Example Response

{
  "upserted_count": 2
}

UPDATE_VECTOR_TABLE_ANNOTATION

Use the DBMS_VECTOR_DATABASE.UPDATE_VECTOR_TABLE_ANNOTATION PL/SQL function to update the public comment and annotations of a vector table.

Purpose

Use this function to update user-managed metadata for an existing vector table.

Impacts

Replaces the vector table’s comment and complete annotations JSON. Annotations are not merged, so callers must provide the entire desired document. Commits automatically.

Syntax

DBMS_VECTOR_DATABASE.UPDATE_VECTOR_TABLE_ANNOTATION (
    name                        IN VARCHAR2,
    comment                     IN VARCHAR2 DEFAULT NULL,
    annotations                 IN JSON DEFAULT NULL,
    debug_flags                 IN JSON DEFAULT NULL,
    request_id                  IN VARCHAR2 DEFAULT NULL
)return CLOB;

Parameters

Parameters	Type	Value Range	Required	Description	Notes
name	VARCHAR2	Existing vector table	Yes	Name of the table to update	Must exist in caller schema
comment	VARCHAR2	String or NULL	No	Updated table comment	Returned as comment in table metadata
annotations	JSON	Object or NULL	No	Updated annotations	Must be valid JSON
debug_flags	JSON	Object or NULL	No	Debug/ tracing flags	Optional
request_id	VARCHAR2	1-256 effective chars	No	Correlation ID	Optional

Example

dbms_vector_database.update_vector_table_annotation(
    name => 'product_vectors',
    comment => 'Updated product embeddings',
    annotations => JSON('{"domain": "retail", "owner": "search"}')
);

Example Response

{
  "table_name": "PRODUCT_VECTORS",
  "comment": "Updated product embeddings",
  "table_params": {
    "auto_generate_id": false
  },
  "annotations": {
    "domain": "retail",
    "owner": "search"
  },
  "vector_type": "dense",
  "vector_table_type": "BYOV",
  "embed_params": null,
  "index_params": {
    "vector_index_params": {
      "auto_index": true
    },
    "metadata_index_params": {
      "auto_index": true
    },
    "parallel_creation": 1
  },
  "owner": "APPUSER",
  "indexes": [],
  "status": "Empty",
  "stats": {
    "total_vectors": 0
  },
  "created": "2026-05-01T10:00:00.000000+00:00",
  "updated": "2026-05-02T09:30:00.000000+00:00"
}

Shared Parameter Objects

Use the following shared object definitions for PL/SQL JSON parameters that accept nested configuration objects.

• advanced_params

• embed_params

• index_params

• metadata_index_params

• table_params

• vector_index_params

advanced_params

advanced_params controls vector index tuning.

Field	Type	Value Range	Required	Description	Notes
partitions	Integer	1-10000000	No	IVF or partition count	Applies to PARTITIONS
neighbors	Integer	1-2048	No	HNSW graph neighbor count	Applies to INMEMORY GRAPH
efConstruction	Integer	1-65535	No	HNSW construction beam width	Applies toINMEMORY GRAPH
rescore_factor	Integer	1-100	No	Rescore factor for HNSW or query-time search tuning	Supported for INMEMORY GRAPH andSEARCH.advanced_options.advanced_params
algorithm	String	uniform_quantization	No	HNSW quantization algorithm	Used with scalar quantization settings

embed_params

embed_params defines how the database generates embeddings automatically from metadata content.

Use embed_params when the table should store vectors generated from text in each row’s metadata JSON. Set model to a loaded embedding model. Set ` embed_metadata_jsonpath ` to the metadata field that contains the text to embed, such as description, $.description, or $.details.summary.

To select metadata content for embedding, choose the field that contains the natural-language text. For metadata such as {"description":"Compact wireless headphones","details":{"summary":"Noise-canceling audio"}}, use description or $.description to embed the top-level description, or use $.details.summary to embed the nested summary. Other metadata fields remain available for filtering or indexing, but they can not be used as embedding input by this setting.

Field	Type	Value Range	Required	Description	Notes
model	String	1-128 chars	Yes	Name of the loaded embedding model to use for automatic embedding.	Model must exist in the caller schema. Use a model name returned by LIST_MODELS. Load one with LOAD_MODEL, if needed.
embed_metadata_jsonpath	String	1-128chars	Yes	Metadata field or JSON path that selects the text value to embed.	Use a simple field name, such as description, or a JSON path, such as $.details.summary. Each inserted or loaded row’s metadata must contain this path, and the selected value should be text. Leading $, $., and extra dots are normalized.

index_params

index_params defines how vector and metadata indexes are created and managed.

Field	Type	Value Range	Required	Description	Notes
index_type	String	vector, metadata, all	No	Index rebuild or drop scope.	<p> <ul id="GUID-6B92DAD4-240A-4550-BD32-166B03F9A996__UL_Q2M_TTX_TJC" style="list-style-type: disc;"> <li>Use with REBUILD_INDEX orDROP_INDEX: - Value vector selects vector index. -Valuemetadata selects metadata indexes. - Value all selects both. </li> <li>ForREBUILD_INDEX: - Omit index_type to rebuild only the index indicated by the supplied nested parameters. - Set it to all to rebuild both indexes. - Omit it for create operations. </li> </ul> </p>
vector_index_params	Object	vector_index_params object	No	Controls how the vector index is built and managed.	Contains vector index settings and advanced tuning parameters.
metadata_index_params	Object	metadata_index_params object	No	Controls how metadata JSON paths are indexed and maintained.	Supports automatic path discovery and explicit include or exclude overrides.
parallel_creation	Integer or null	>= 1	No	Controls index creation or rebuild parallelism.	Uses parallel DDL for vector and metadata index creation when supported; defaults to 1 when normalized.

metadata_index_params

metadata_index_params creates indexes on metadata paths used in filters, helping reduce filtering cost and improve filtered-search performance.

Field	Type	Value Range	Required	Description	Notes
auto_index	Boolean	true, false	No	Controls whether metadata indexes are automatically created and maintained.	Defaults totrue in create flows. When true, the database automatically creates and maintains indexes on qualifying metadata paths, up to the supported limit. When false, only user-specified paths are indexed.
include_paths	Array of string	JSON paths or *	No	Explicit list of metadata JSON paths to include in metadata indexing.	Use explicit paths, such as year ordetails.genre, to force those paths into the metadata index selection. Use *to request all qualifying paths. Exact paths are normalized.
exclude_paths	Array of string	JSON paths or *	No	Explicit list of metadata JSON paths to exclude from metadata indexing.	Use explicit paths to override automatic selection or an include_paths wildcard. Usinginclude_paths=["*"] withexclude_paths=["*"]is invalid.

Metadata indexing supports up to the first 50 qualifying paths when automatic path discovery is used. Qualifying paths are scalar metadata values that can be indexed. Arrays, objects, strings longer than 2 KB, and the path referenced by embed_metadata_jsonpath are not qualifying metadata index paths.

Use these common patterns:

Automatically discover and index qualifying metadata paths, up to the supported limit:

{
  "metadata_index_params": {
    "auto_index": true
  }
}

Index only the selected metadata paths:

{
  "metadata_index_params": {
    "auto_index": false,
    "include_paths": ["year", "genre"]
  }
}

Request all qualifying metadata paths except the excluded paths:

{
  "metadata_index_params": {
    "include_paths": ["*"],
    "exclude_paths": ["title"]
  }
}

table_params

table_params defines table creation options.

Field	Type	Value Range	Required	Description	Notes
auto_generate_id	Boolean	true, false	No	Controls whether the database automatically generates IDs for inserted records	Defaults to false. When set to true, the database automatically generates an ID for each vector that does not provide an explicit ID. You can still use upsert or load operations with explicit IDs.

vector_index_params

vector_index_params controls vector index configuration. It defines how the vector index is built and managed, including vector index settings and advanced tuning parameters.

Field	Type	Value Range	Required	Description	Notes
auto_index	Boolean	true, false	No	Controls whether the vector index is created automatically or only when requested explicitly.	Defaults to true when vector parameters are normalized. Set to false when you want to create or manage the vector index through explicit index lifecycle operations.
organization	String	PARTITIONS, INMEMORY GRAPH	No	Controls vector index organization.	Defaults to PARTITIONS. PARTITIONS builds an IVF index, and INMEMORY GRAPH builds an HNSW index.
distance_metric	String	MANHATTAN, DOT, COSINE, EUCLIDEAN, EUCLIDEAN_SQUARED, L2_SQUARED	No	Distance or similarity metric used by the vector index.	Defaults to COSINE when omitted. Validation is case-insensitive. For more information, see . Vector Distance Metrics
accuracy	Integer	0-100	No	Controls target index accuracy.	Optional tuning parameter. The implementation default is used when omitted. Use this value to adjust the trade-off between speed and accuracy. For more information, see Understand Approximate Similarity Search
quantization_type	String or null	NONE , SCALAR	No	Vector index quantization mode.	Use SCALAR with compression_ratio to compress vectors. Omit or use NONE when scalar quantization is not needed. Quantization is supported only with HNSW indexes.
compression_ratio	Number or null	2, 4, 8	No	Controls how much to compress vectors when scalar quantization is enabled.	Populate when quantization_type is SCALAR. Valid values are 2, 4, and 8.
advanced_params	Object	advanced_params object	No	Advanced vector index tuning parameters.	Supported fields depend on organization. Use partitions with PARTITIONS; use graph parameters, such as neighbors and efConstruction, with INMEMORY GRAPH.