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.

Note: With integrated embedding, text is embedded inline by the embedding model loaded in Oracle AI Database. Embedding, therefore, uses database CPU resources and adds embedding time to upsert, load, and query operations. For embedding-intensive or latency-sensitive workloads, consider generating embeddings separately, for example, with OCI Generative AI and supplying precomputed vectors.

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

Caution: After creating a vector table by using DBMS_VECTOR_DATABASE, drop the table only by using DBMS_VECTOR_DATABASE.DROP_VECTOR_TABLE.

Do not drop a vector table created through DBMS_VECTOR_DATABASE by using DROP TABLE or another database API. Doing so can remove the underlying database table without removing the DBMS_VECTOR_DATABASE metadata that references it.

This can leave an invalid vector table entry. For example, DBMS_VECTOR_DATABASE.LIST_VECTOR_TABLES might return a table whose details are NULL, and subsequent DBMS_VECTOR_DATABASE operations on that table can fail. To remove a vector table created through DBMS_VECTOR_DATABASE, use the following syntax:

BEGIN
 DBMS_VECTOR_DATABASE.DROP_VECTOR_TABLE('<table_name>');
END;
/

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 manual indexing
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.

Example response:

{
    "table_name": "DEMO_PRODUCTS",
    "owner": "VECTOR3",
    "status": "Empty",
    "vector_type": "dense",
    "vector_table_type": "BYOV",
    "index_params": {
        "vector_index_params": {
            "auto_index": true,
            "organization": "PARTITIONS",
            "advanced_params": {
                "partitions": 10
            }
        },
        "parallel_creation": 4
    },
    "annotations": {
        "metric": "cosine",
        "dimension": "5"
    },
    "created": "2026-03-12T11:21:30Z"
}

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

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.

For more information about POST /vecdb/vector-tables, see REST API Reference.

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

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