Shared Parameter Objects

Use these shared object definitions for method parameters that accept nested configuration objects.

`table_params`

table_params defines table creation options.

Field	Type	Value Range	Required	Description	Notes
`auto_generate_id`	`bool`	`true`, `false`	No	Controls whether the database automatically generates IDs for inserted records.	Defaults to `false`; set to `true` when callers do not provide explicit IDs.

`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 dictionary. Set model to a loaded embedding model. Set embed_metadata_jsonpath to the metadata field that contains the text to embed, such as 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 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 are not used as embedding input by this setting.

Resource usage: Configuring embed_params causes embedding to occur inside Oracle AI Database whenever an operation supplies text that requires a vector. The embedding work uses database CPU resources and is performed inline with the operation. Consider workload volume and latency requirements when choosing between integrated embedding and precomputed vectors.

Field	Type	Value Range	Required	Description	Notes
`model`	`str`	1-128 chars	Yes	Name of the loaded embedding model to use for automatic embedding.	Model must exist in the database schema. Use a model name returned by `list_models()`; load one with `load_model()` if needed.
`embed_metadata_jsonpath`	`str`	1-128 chars	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, upserted, or loaded row’s metadata must contain this path, and the selected value should be text.

`index_params`

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

The SDK validates this object before sending a request. Use only the documented snake-case fields; unsupported or legacy camel-case fields are rejected. When distribute_params is an object, it must contain only distribute_method, and that field cannot be null.

Field	Type	Value Range	Required	Description	Notes
`index_type`	`str`	`vector`, `metadata`, `all`	No	Index rebuild or drop scope.	Use with `rebuild_index()` or `drop_index()` to target vector indexes, metadata indexes, or all indexes. For rebuild, omit to infer the target from supplied `vector_index_params` or `metadata_index_params`; use `all` when metadata parameters are supplied and the vector index should also be rebuilt. Omit for create flows.
`vector_index_params`	`dict`	`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`	`dict`	`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`	`int` or `None`	>= 1	No	Controls index creation or rebuild parallelism.	Uses parallel DDL for vector and metadata index creation when supported; defaults to `1` when normalized.

`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`	`bool`	`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`	`str`	`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`	`str`	`MANHATTAN`, `HAMMING`, `DOT`, `COSINE`, `EUCLIDEAN`, `EUCLIDEAN_SQUARED`, `JACCARD`, `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`	`int`	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 Using Vector Indexes.
`quantization_type`	`str` or `None`	`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`	`float` or `None`	`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`.
`distribute_params`	`dict` or `None`	Object or NULL	No	Controls distribution for HNSW vector indexes in a clustered environment.	Applies to `INMEMORY GRAPH`.
`advanced_params`	`dict`	`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`.

`distribute_params`

distribute_params controls how HNSW vector index data is distributed across nodes in a clustered environment.

Field	Type	Value Range	Required	Description	Notes
`distribute_method`	`str`	`ROWID RANGE`, `AUTO`	No	Determines how vector index data is distributed across nodes.	Applies when `organization` is `INMEMORY GRAPH`.

distribute_method supports the following values:

ROWID RANGE: Splits rows into sequential row ranges across nodes.
AUTO: Automatically selects the distribution method based on the table structure and workload.

`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`	`bool`	`true`, `false`	No	Controls whether metadata indexes are automatically created and maintained.	Defaults to `true` 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`	`list`	JSON paths or `*`	No	Explicit list of metadata JSON paths to include in metadata indexing.	Use explicit paths, such as `year` or `details.genre`, to force those paths into the metadata index selection. Use `*` to request all qualifying paths. Exact paths are normalized.
`exclude_paths`	`list`	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. `include_paths=[""]` with `exclude_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:

{
    'metadata_index_params': {
        'auto_index': True
    }
}

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

{
    'metadata_index_params': {
        'auto_index': False,
        'include_paths': ['year', 'genre']
    }
}

Index only the selected metadata paths.

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

Request all qualifying metadata paths except the excluded paths.

`advanced_params`

advanced_params controls vector index tuning.

Field	Type	Value Range	Required	Description	Notes
`partitions`	`int`	1-10000000	No	IVF or partition count.	Applies to `PARTITIONS`.
`neighbors`	`int`	1-2048	No	HNSW graph neighbor count.	Applies to `INMEMORY GRAPH`.
`efConstruction`	`int`	1-65535	No	HNSW construction beam width.	Applies to `INMEMORY GRAPH`.
`rescore_factor`	`int`	1-100	No	Rescore factor for HNSW vector index tuning.	Applies to `INMEMORY GRAPH`.
`algorithm`	`str`	`uniform_quantization`	No	HNSW quantization algorithm.	Used with scalar quantization settings.