Create a Vector Table

Use the create vector table operation to create a new vector table for storing vector embeddings.

The operation creates a vector table with a fixed schema optimized for vector search. The table includes columns for ID, vector data, and JSON metadata. You can configure automatic ID generation, embedding integration, and index parameters during creation.

If the table already exists or if invalid parameters are provided, an error is raised.

See the following example for different variations of table creation using create_vector_table():

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

#create a table for pre-computed vectors
prod_vec_response = client.create_vector_table(
    name="product_vectors",
    comment="Product embeddings",
    table_params={"auto_generate_id": True},
    index_params={
        "vector_index_params": {
            "auto_index": True,
            "organization": "PARTITIONS",
            "distance_metric": "COSINE",
        }
    },
)
print(prod_vec_response)

#create a table with integrated embedding
docs_response = client.create_vector_table(
    name="documents",
    table_params={"auto_generate_id": True},
    embed_params={
        "model": "all_MiniLM_L12_v2",
        "embed_metadata_jsonpath": "content",
    },
)
print(docs_response)
#create a table for bring-your-own vectors with cust_vec_response = client.create_vector_table(
cust_vec_response = client.create_vector_table(
    name="customer_vectors",
    comment="Manually managed vector table",
    index_params={
        "vector_index_params": {
            "auto_index": False,
        }
    },
)
print(cust_vec_response)

A JSON response containing the created table details and status is returned.

The following parameters are accepted as input:

Parameter	Type	Description
`table_name`	`str`	Name of the vector table to create. The provided name must be unique within the database.
`description`	`str`	An optional, human-readable description of the table's purpose.
`auto_generate_id`	`bool`	If set to `true`, automatically generates unique IDs for vectors on insert. If set to `false`, IDs must be provided explicitly. This is an optional parameter and is set by default to `false`.
`annotations`	`str`	You can optionally provide key-value pairs for custom metadata about the table. For example: `{ 'application': 'chatbot', 'department': 'sales' }`
`vector_type`	`str`	Optionally specify the type of vectors to store. Currently, only `dense` vectors are supported. The default value is `dense`.
`embed_params`	`dict`	Optionally provide configuration for an integrated embedding mode. If provided, the table will automatically generate embeddings on insert. For example: `{ 'model': 'all_MiniLM_L12_v2', 'embed_metadata_jsonpath': 'content' }`
`index_params`	`dict`	Optionally provide configuration for vector index creation. This parameter supports both automatic and manual indexing strategies. For example: For auto-managed IVF indexes: `{ 'indexing': 'auto', 'organization': 'PARTITIONS', 'advanced_params': { 'type': 'IVF', 'partitions': 5 } }` To defer creation and later supply detailed settings (such as distance metric, organization, IVF/HNSW parameters) when using the `create index` operation: `{ 'indexing': 'manual' }`
`debug_flags`	`dict`	Optionally provide debug configuration for detailed logging.

See the following examples of table creation using POST /vecdb/vector-tables:

Create a table for bring-your-own vectors:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/vector-tables/" \
  -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 '{
    "name": "product_vectors",
    "comment": "Product catalog embeddings",
    "tableParams": {
      "auto_generate_id": false
    },
    "annotations": {
      "domain": "retail"
    },
    "indexParams": {
      "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
    }
  }'

Create a model-backed table:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/vector-tables/" \
  -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 '{
    "name": "product_text_vectors",
    "comment": "Product text embeddings",
    "tableParams": {
      "auto_generate_id": true
    },
    "embedParams": {
      "model": "DOC_EMBED_MODEL",
      "embed_metadata_jsonpath": "description"
    },
    "indexParams": {
      "vector_index_params": {
        "auto_index": true,
        "organization": "INMEMORY GRAPH",
        "distance_metric": "COSINE"
      }
    }
  }'

Responses:

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

400 - invalid or missing parameters, including invalid nested object fields or unsupported combinations.
409 - a table with that name already exists.

The following parameters are accepted as part of the request body:

Parameter	Type	Description
`name`	`string`	Name of the vector table to create. The provided name must be unique within the database.
`comment`	`string`	An optional, human-readable description of the table's purpose.
`annotations`	`object`	You can optionally provide key-value pairs for custom metadata about the table.
`tableParams`	`object`	Optionally provide table-level creation parameters, such as `auto_generate_id`. If set to `true`, `auto_generate_id`automatically generates unique IDs for vectors on insert. If set to `false`, IDs must be provided explicitly. This is an optional parameter and is set by default to `false`.
`embedParams`	`object`	Optionally specify automatic embedding configuration for model-backed tables. Supply this parameter when the table should generate vectors from metadata text by using a loaded embedding model. Omit for bring-your-own-vector tables.
`indexParams`	`object`	Optionally set vector and metadata index configuration. The following fields can be specified: `index_type` `vector_index_params` `metadata_index_params` `parallel_creation`
`debugFlags`	`object`	Optionally provide debug configuration for detailed logging.

Response fields:

Field	Type	Description
`table_name`	`string`	The name of the table.
`comment`	`string`	Description of the vector table. Nullable.
`auto_generate_id`	`integer`	Whether the ID column is auto-generated.
`owner`	`string`	Database owner of the table.
`status`	`string`	Population status of the vector table.
`vector_table`	`string`	`"dense"`
`vector_table_type`	`string`	`"BYOV"` or `"MODEL"`
`index_params`	`object`	Index configuration with fields `indexing`, `organization`, `distance_metric`, `accuracy`, and `advanced_params`. Nullable.
`annotations`	`object` or `string`	User metadata attached to the table. Nullable.
`embed_params`	`object`	Embedding model configuration for `MODEL` tables, with fields `model` and `embed_metadata_jsonpath`. Nullable.
`dense_idx_name`	`string`	Name of the vector index associated to the table. Nullable.
`stats`	`object`	Table statistics. Contains `total_vectors` (number, nullable).
`created`	`string` (date-time)	Creation timestamp.
`updated`	`string` (date-time)	Last updated timestamp. Nullable.

For more information, see Create a vector table.

See how DBMS_VECTOR_DATABASE.CREATE_VECTOR_TABLE can be used in the following 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"
}