Python API Reference
A complete reference for Infinity's Python APIs.
SCHEMA MANAGEMENT
connect
# Connect to the Infinity server and get an Infinity object
infinity.connect(uri)
Connects to the Infinity server, and gets an Infinity object.
You must have an Infinity object ready to perform database-specific operations.
Parameters
uri: Required
The uri here is a NetworkAddress object:
NetworkAddress: Used in client-server mode, when you have deployed Infinity as a separate server and wish to connect to it remotely. A NetworkAddress object comprises two fields:
"<SERVER_IP_ADDRESS>":str- The IP address of the Infinity server.<PORT>:int- The SDK port number on which the Infinity server listens. Defaults to23817.
When setting uri as NetworkAddress, ensure you:
- Install the Infinity SDK:
pip install infinity==<VERSION> - Import the
infinitymodule:import infinity.
When connecting to Infinity in client-server mode, ensure that the client version exactly matches the server version. For example:
| Client version | Server version |
|---|---|
| v0.1.0 | v0.1.0 |
| v0.1.1 | v0.1.1 |
| v0.2.0 | v0.2.0 |
| v0.2.1 | v0.2.1 |
| v0.3.0 | v0.3.0 |
| v0.4.0 | v0.4.0 |
| v0.5.0-dev2 | v0.5.0-dev2 |
If the versions do not match, please update your client or server to ensure compatibility.
In client-server mode, also ensure that your server version matches the version specified in your configuration file. Here, the matching rule is less strict than an exact match:
- The major and minor versions must be identical.
- The patch version may differ.
This allows for bug fixes without requiring changes to the configuration file.
| Configuration version | Compatible server version |
|---|---|
| v0.1.0 | v0.1.0, v0.1.1 |
| v0.2.0 | v0.2.0, v0.2.1 |
Returns
- Success: An
infinity.remote_thrift.infinity.RemoteThriftInfinityConnectionobject in client-server mode. - Failure:
InfinityExceptionerror_code:int- A non-zero value indicating a specific error condition.error_msg:str- A message providing additional details about the error.
Examples
Connect to Infinity in client-server mode
If you have deployed Infinity as a separate server and installed the Infinity client via pip install infinity==<VERSION>, you can connect to it via its IP address. If your Infinity is running on your local machine, you can also use infinity.common.LOCAL_HOST to replace "<SERVER_IP_ADDRESS>" in the following code snippet.
import infinity
# If Infinity is deployed on the local machine, use infinity.LOCAL_HOST to replace <SERVER_IP_ADDRESS>
infinity_object = infinity.connect(infinity.NetworkAddress("192.168.1.101", 23817))
disconnect
infinity_object.disconnect()
Disconnects the client from the Infinity server in client-server mode, or destructs the Infinity object and releases all associated resources when Infinity is imported as a Python module.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
infinity_object.disconnect()
create_database
infinity_object.create_database(db_name, conflict_type=ConflictType.Error, comment=None)
Creates a database with a specified name.
Parameters
db_name: str, Required
A non-empty string indicating the name of the database, which must adhere to the following requirements:
- Permitted characters include:
- English letters (a-z, A-Z)
- Digits (0-9)
- "_" (underscore)
- Must begin with an English letter or underscore.
- Maximum 65,535 characters.
- Case-insensitive.
conflict_type: ConflictType, Optional
Error: Raise an error if a database with the same name exists.Ignore: Ignore the database creation request and keep the existing database with the same name.
You may want to import the infinity.common package to set ConflictType:
from infinity.common import ConflictType
If ConflictType is not set, it defaults to Error.
comment: str, Optional
Additional comment for the database to create.
Returns
- Success: An
infinity.remote_thrift.db.RemoteDatabaseobject in client-server mode. - Failure:
InfinityExceptionerror_code:int- A non-zero value indicating a specific error condition.error_msg:str- A message providing additional details about the error.
Examples
# Create a database named 'my_database':
# If the specified database already exists, raise an error.
infinity_object.create_database("my_database")
# Create a database named 'my_database':
# If the specified database already exists, raise an error (same as above).
infinity_object.create_database(
"my_database", infinity.common.ConflictType.Error, comment="Database One"
)
from infinity.common import ConflictType
# Create a database named 'my_database':
# If the specified database already exists, silently ignore the operation and proceed.
infinity_object.create_database(
"my_database", ConflictType.Ignore, comment="Database One"
)
drop_database
infinity_object.drop_database(db_name, conflict_type=ConflictType.Error)
Deletes a database by its name.
Parameters
db_name: str, Required
A non-empty string indicating the name of the database to delete.
conflict_type: ConflictType, Optional
Error: Raise an error if the specified database does not exist.Ignore: Ignore the operation and proceed regardless, if the specified database does not exist.
You may want to import the infinity.common package to set ConflictType:
from infinity.common import ConflictType
If ConflictType is not set, it defaults to Error.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
# Delete a database named 'my_database':
# If the specified database does not exist, raise an error.
infinity_object.drop_database("my_database")
# Delete a database named 'my_database':
# If the specified database does not exist, raise an error (same as above).
infinity_object.drop_database("my_database", infinity.common.ConflictType.Error)
from infinity.common import ConflictType
# Delete a database named 'my_database':
# If the specified database does not exist, silently ignore the operation and proceed.
infinity_object.drop_database("my_database", ConflictType.Ignore)
list_databases
infinity_object.list_databases()
Retrieves a list of all available databases within the Infinity system.
Returns
A structure containing the following attributes:
db_names:list[str]A list of strings indicating the names of all available databases.error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
res = infinity_object.list_databases()
print(res.db_names) # ['my_database', 'database_1']
show_database
infinity_object.show_database(database_name)
Shows detailed information about a database.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
res = infinity_object.show_database("my_database")
get_database
infinity_object.get_database(database_name)
Retrieves a database object by its name.
Parameters
db_name: str, Required
A non-empty string indicating the name of the database to retrieve.
Returns
- Success: An
infinity.remote_thrift.db.RemoteDatabaseobject in client-server mode. - Failure:
InfinityExceptionerror_code:int- A non-zero value indicating a specific error condition.error_msg:str- A message providing additional details about the error.
Examples
db_object = infinity_object.get_database("my_database")
create_table
db_object.create_table(table_name, columns_definition, conflict_type=ConflictType.Error)
Creates a table with a specified name and defined columns.
Call create_database() or get_database() to get a database object for all table-specific operations.
Parameters
table_name: str, Required
A non-empty string indicating the name of the table, which must adhere to the following requirements:
- Permitted characters include:
- English letters (a-z, A-Z)
- Digits (0-9)
- "_" (underscore)
- Must begin with an English letter or underscore.
- Maximum 65,535 characters.
- Case-insensitive.
columns_definition: dict[str, dict[str, Any]], Required
Definitions for all table columns as a dictionary. Each key in the dictionary is a column name (a str following the same rule as table_name), with a corresponding 'value' dictionary defining the column's data type and default value information in key-value pairs:
- Data type (
"type")
The data type of the column.- Numeric:
"int8""int16""int"/"int32"/"integer""int64""float"/"float32""double"/"float64""float16""bfloat16"
- String:
"varchar" - Dense vector: e.g.,
"vector,128,float"vector: The column is a dense vector column.- The second item in the string: The dimension of dense vector.
- The third item in the string: The element type of dense vector. Can be:
"int8""int16""int"/"int32"/"integer""int64""float"/"float32""double"/"float64""float16""bfloat16"
- Sparse vector: e.g.,
"sparse,128,float,int"sparse: The column is a sparse vector column.- The second item in the string: The dimension of sparse vector.
- The third item in the string: The element type of sparse vector. Can be:
"int8""int16""int"/"int32"/"integer""int64""float"/"float32""double"/"float64""float16""bfloat16"
- The fourth item in the string: The data type of sparse vector indices. Can be:
int8int16int/int32/integerint64
- Tensor vector: e.g.,
"tensor,4,float"tensor: The column is a tensor column.- The second item in the string: The dimension of each vector unit in a tensor.
- The third item in the string: The element type of tensors. Can be:
"int8""int16""int"/"int32"/"integer""int64""float"/"float32""double"/"float64""float16""bfloat16"
- Tensor array: e.g.,
"tensorarray,6,float"tensorarray: The column is a tensor-array column.- The second item in the string: The dimension of each vector unit in a tensor array.
- The third item in the string: The element type of tensor arrays. Can be:
"int8""int16""int"/"int32"/"integer""int64""float"/"float32""double"/"float64""float16""bfloat16"
- Multivector: e.g.,
"multivector,128,float"multivector: The column is a multi-vector column.- The second item in the string: The dimension of each vector unit in a multivector.
- The third item in the string: The element type of multi-vectors. Can be:
"int8""int16""int"/"int32"/"integer""int64""float"/"float32""double"/"float64""float16""bfloat16"
- Array: e.g.,
"array,varchar","array,array,varchar"array: The column is an array column.- followed by the element type of the array. Can be recursive.
- for example,
"array,varchar"is a one-dimensional array of strings, and"array,array,varchar"is a two-dimensional array of strings.
- Numeric:
- Default value (
"default")
The default value for unspecified cells in that column.
conflict_type: ConflictType, Optional
Error: Raise an error if a table with the same name exists.Ignore: Ignore the table creation request and keep the existing table with the same name.
You may want to import the infinity.common package to set ConflictType:
from infinity.common import ConflictType
If ConflictType is not set, it defaults to Error.
Returns
- Success: An
infinity.remote_infinity.table.RemoteTableobject in client-server mode. - Failure:
InfinityException:error_code:int- A non-zero value indicating a specific error condition.error_msg:str- A message providing additional details about the error.
Examples
Create a table with an integer column only
# The `create_table`method supports creating integer columns in the following data types:
# - int8
# - int16
# - int/int32/integer
# - int64
db_object.create_table("my_table", {"c1": {"type": "int", "default": 1}})
Create a table with a float column only
# The `create_table`method supports creating float columns in the following data types:
# - float/float32
# - double/float64
# - float16
# - bfloat16
db_object.create_table("my_table", {"c1": {"type": "float64"}})
Create a table with a string column only
db_object.create_table("my_table", {"c1": {"type": "varchar"}})
Create a table with a bool column only
db_object.create_table("my_table", {"c1": {"type": "bool"}})
Create a table with a vector column only
You can build a HNSW index on the vector column to speed up the match_dense search.
# Create a table with a vector column only:
# - `vector`: The column is a vector column
# - `128`: The vector dimension
# - `float`: The primitive data type of the vectors. Can be `float`/`float32`, `float16`, `bfloat16`, `uint8` or `int8`
db_object.create_table("my_table", {"c1": {"type": "vector,128,float"}})
Create a table with a multi-vector column only
You can build an HNSW index on the multi-vector column to accelerate match_dense search.
# Create a table with a multi-vector column only:
# - `multivector`: The column is a multi-vector column
# - `128`: The basic vector dimension
# - `float`: The primitive data type of the basic vectors. Can be `float`/`float32`, `float16`, `bfloat16`, `uint8` or `int8`
db_object.create_table("my_table", {"c1": {"type": "multivector,128,float"}})
Create a table with a sparse vector column only
You can build a BMP index on the sparse vector column to speed up the match_sparse search.
from infinity.common import ConflictType
# Create a table with a vector column only:
# - `sparse`: The column is a sparse vector column
# - `128`: The sparse vector dimension
# - `float`: The primitive data type of the sparse vectors. Can be `float`/`float32` or `double`/`float64`
# - `int`: The data type of the sparse vector indices. Can be `int8`, `int16`, `int`/`int32`/`integer`, or `int64`
db_object.create_table(
"my_table", {"c1": {"type": "sparse,128,float,int"}}, ConflictType.Error
)
Create a table with a tensor column only
from infinity.common import ConflictType
# Create a table with a tensor column only:
# - `tensor`: The column is a tensor column
# - `4`: Dimension of each vector unit in the tensor
# - `float`: The primitive data type of the tensors. Can be `float`/`float32`, `float16`, `bfloat16` or `bit`
db_object.create_table(
"my_table", {"c1": {"type": "tensor,4,float"}}, ConflictType.Ignore
)
Create a table with a tensor array column only
from infinity.common import ConflictType
# Create a table with a tensor array column only:
# - `tensorarray`: The column is a tensor array column
# - `6`: Dimension of each vector unit in the tensor arrays
# - `float`: The primitive data type of the tensor arrays. Can be `float`/`float32`, `float16`, `bfloat16` or `bit`
db_object.create_table(
"my_table", {"c1": {"type": "tensorarray,6,float"}}, ConflictType.Ignore
)
drop_table
db_object.drop_table(table_name, conflict_type=ConflictType.Error)
Deletes a table from the database by its name.
Parameters
table_name: str, Required
A non-empty string indicating the name of the table to delete.
conflict_type: ConflictType, Optional
Error: Raise an error if the specified table does not exist.Ignore: Ignore the operation and proceed regardless, if the specified table does not exist.
You may want to import the infinity.common package to set ConflictType:
from infinity.common import ConflictType
If ConflictType is not set, it defaults to Error.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
# Delete a table named 'my_table':
# If the specified table does not exist, raise an error.
db_object.drop_table("my_table")
# Delete a table named 'my_table':
# If the specified table does not exist, raise an error (same as above).
db_object.drop_table("my_table", infinity.common.ConflictType.Error)
from infinity.common import ConflictType
# Delete a table named 'my_table':
# If the specified table does not exist, silently ignore the operation and proceed.
db_object.drop_table("my_table", ConflictType.Ignore)
create_table_snapshot
db_object.create_table_snapshot(snapshot_name, table_name)
Creates a snapshot of the specified table with the given snapshot name.
Parameters
snapshot_name: str, Required
A non-empty string indicating the name of the table snapshot.
table_name: str, Required
A non-empty string indicating the name of the table.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
# Create a snapshot named 'my_table_snapshot' of the table 'my_table'.
# If the specified snapshot already exists or the specified table does not exist, raise an error.
db_object.create_table_snapshot("my_table_snapshot", "my_table")
create_database_snapshot
infinity_obj.create_database_snapshot(snapshot_name, database_name)
Creates a snapshot of the specified database with the given snapshot name.
Parameters
snapshot_name: str, Required
A non-empty string indicating the name of the database snapshot.
database_name: str, Required
A non-empty string indicating the name of the database.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
# Create a snapshot named 'my_database_snapshot' of the database 'my_database'.
# If the specified snapshot already exists or the specified database does not exist, raise an error.
infinity_obj.create_database_snapshot("my_database_snapshot", "my_database")
create_system_snapshot
infinity_obj.create_system_snapshot(snapshot_name)
Creates a snapshot of the system with the given snapshot name.
Parameters
snapshot_name: str, Required
A non-empty string indicating the name of the system snapshot.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
# Create a snapshot named 'my_system_snapshot'.
# If the specified snapshot already exists, raise an error.
infinity_obj.create_system_snapshot("my_system_snapshot")
restore_table_snapshot
db_object.restore_table_snapshot(snapshot_name)
Restores a table from the specified snapshot.
Parameters
snapshot_name: str, Required
A non-empty string indicating the name of the table snapshot.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
# Restore a table from the snapshot 'my_table_snapshot'.
# If the specified snapshot does not exist, raise an error.
db_object.restore_table_snapshot("my_table_snapshot")
restore_database_snapshot
infinity_obj.restore_database_snapshot(snapshot_name)
Restores a database from the specified snapshot.
Parameters
snapshot_name: str, Required
A non-empty string indicating the name of the database snapshot.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
# Restore a database from the snapshot 'my_database_snapshot'.
# If the specified snapshot does not exist, raise an error.
infinity_obj.restore_database_snapshot("my_database_snapshot")
restore_system_snapshot
infinity_obj.restore_system_snapshot(snapshot_name)
Restores a system from the specified snapshot.
Parameters
snapshot_name: str, Required
A non-empty string indicating the name of the system snapshot.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
# Restore a system from the snapshot 'my_system_snapshot'.
# If the specified snapshot does not exist, raise an error.
infinity_obj.restore_system_snapshot("my_system_snapshot")
drop_snapshot
infinity_obj.drop_snapshot(snapshot_name)
Deletes a snapshot with the specified name.
Parameters
snapshot_name: str, Required
A non-empty string indicating the name of the snapshot.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
# Delete a snapshot named 'my_snapshot':
# If the specified snapshot does not exist, raise an error.
infinity_obj.drop_snapshot("my_snapshot")
add_columns
table_object.add_columns(column_defs)
Parameters
column_defs: dict[str, dict[str, Any]], Required
A dictionary defining the columns to add. Each key in the dictionary is a column name (str), with a corresponding 'value' dictionary defining the column's data type and default value. See the description of create_table()'s columns_definition for all available settings.
You must specify a default value each time you add a column.
Examples
Add an Integer column, a float column, and a varchar/string column at once
table_obj.add_columns(
{
"column_name1": {"type": "integer", "default": 0},
"column_name2": {"type": "float", "default": 0.0},
"column_name3": {"type": "varchar", "default": ""},
}
)
Add a dense vector column
table_obj.add_columns(
{"column_name1": {"type": "vector,4,float", "default": [1.0, 1.2, 2.4, 4.6]}}
)
Add a multivector column
table_obj.add_columns(
{
"column_name1": {
"type": "multivector,4,float",
"default": [[1.0, 0.0, 0.0, 0.0], [1.2, 0.0, 0.0, 0.0]],
}
}
)
Add a tensor column
table_obj.add_columns(
{
"column_name1": {
"type": "tensor,4,float",
"default": [[1.0, 0.0, 0.0, 0.0], [1.2, 0.0, 0.0, 0.0]],
}
}
)
Add a sparse column
from infinity.common import SparseVector
table_obj.add_columns(
{
"column_name1": {
"type": "sparse,128,float,int",
"default": SparseVector([10, 20, 30], [1.1, 2.2, 3.3]),
}
}
)
Or, you can set the default value in a different format:
table_obj.add_columns(
{
"column_name1": {
"type": "sparse,128,float,int",
"default": {"10": 1.1, "20": 2.2, "30": 3.3},
}
}
)
drop_columns
table_object.drop_columns(column_names)
Parameters
column_names: list[str], Required
A list of strings representing the names of the columns to drop.
Examples
Remove one column from the table
table_object.drop_columns(["column_name"])
Remove two columns at once
table_object.drop_columns(["column_name1", "column_name2"])
get_table
db_object.get_table(table_name)
Retrieves a table object by its name.
Parameters
table_name: str, Required
A non-empty string indicating the name of the table to retrieve.
Returns
- Success: An
infinity.remote_infinity.table.RemoteTableobject in client-server mode. - Failure:
InfinityException:error_code:int- A non-zero value indicating a specific error condition.error_msg:str- A message providing additional details about the error.
Examples
table_object = db_object.get_table("my_table")
show_columns
table_object.show_columns()
Show the column definition of the current table.
Returns
An infinity.remote_thrift.table.RemoteTable object in client-server mode.
This method specifies the projection columns for the current table but does not directly produce displayable data. To display the query results, use output() in conjunction with methods like to_result(), to_df(), to_pl(), or to_arrow() to materialize the data.
Examples
res = table_object.show_columns()
print(res)
list_tables
db_object.list_tables()
Retrieves a list of all available tables within the current database.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.table_names:list[str]- A list of strings indicating the names of all available tables in the current database.
Examples
res = db_object.list_tables()
res.table_names # ['my_table, 'tensor_table', 'sparse_table']
show_table
db_object.show_table(table_name)
Shows detailed information about a table.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
res = db_object.show_table("my_table")
create_index
table_object.create_index(
index_name, index_info, conflict_type=ConflictType.Error, comment=None
)
Creates an index on a specified column.
Call create_table() or get_table() to get a database object for all index-specific operations.
Parameters
index_name: str Required
A non-empty string indicating the name of the index, which must adhere to the following requirements:
- Permitted characters include:
- English letters (a-z, A-Z)
- Digits (0-9)
- "_" (underscore)
- Must begin with an English letter or underscore.
- Maximum 65,535 characters.
- Case-insensitive.
index_info: IndexInfo(), Required
An IndexInfo structure contains three fields,column_name, index_type, and index_param_list.
- column_name:
str, Required
The name of the column to build index on. Must not be empty. - index_type:
IndexType, Required
Index type. You may want to importinfinity.indexto setIndexType:from infinity.index import IndexTypeHnsw: An HNSW index. Works with dense vectors, and multivectors only.IVF: An IVF index. Works with dense vectors and multivectors only.FullText: A full-text index.Secondary: A secondary index. Works with structured data only.BMP: A Block-Max Pruning index. Works with sparse vectors only.
- index_param_list:
dict[str, str]
A dictionary specifying the parameter settings for the selected index type. Each key-value pair in the dictionary corresponds to a parameter and its value:- Parameter settings for an HNSW index:
"M": Optional - Defaults to"16"."ef_construction": Optional - Defaults to"50"."metric"Required - The distance metric to use in similarity search."ip": Inner product."l2": Euclidean distance."cosine": Cosine similarity.
"encode": Optional"plain": (Default) Plain encoding."lvq": Locally-adaptive vector quantization. Works with float vector element only.
"build_type": Optional"plain": (Default) Plain build."lsg": Local scaling graph.
"lsg_config": Optional - A dictionary with each key-value pair corresponding to a parameter setting of the local scaling graph:"sample_raito": Optional - Defaults to"0.01". The ratio of the number of samples in the dataset (base)."ls_k": Optional - Defaults to"10". The number of nearest neighbors of the selected knn mean in local scaling."alpha": Optional - Defaults to"1.0". The smoothing factor in local scaling.
- Parameter settings for an IVF index:
"metric"Required - The distance metric to use in a similarity search."ip": Inner product."l2": Euclidean distance."cosine": Cosine similarity.
"storage_type": Optional"plain": (Default) Plain storage."scalar_quantization": Scalar quantization."product_quantization": Product quantization.
"plain_storage_data_type": Optional for plain storage."int8": default value forint8embeddings."uint8": default value foruint8embeddings."float32": default value for floating-point embeddings."float16": for floating-point embeddings."bfloat16": for floating-point embeddings.
"scalar_quantization_bits": Required for scalar quantization. Must be either4or8."product_quantization_subspace_num": Required for product quantization. Must be divisor of the embedding dimension."product_quantization_subspace_bits": Required for product quantization. Must be in the range[4, 16].
- Parameter settings for a full-text index:
"ANALYZER": Optional"standard": (Default) The standard analyzer, segmented by token, lowercase processing, and provides stemming output. Use-to specify the languages' stemmer.Englishis the default stemmer:"standard-english"and"standard"are the same stemmer setting. Supported language stemmers include:Danish,Dutch,English,Finnish,French,German,Hungarian,Italian,Norwegian,Porter,Portuguese,Romanian,Russian,Spanish,Swedish, andTurkish."rag": Multilingual RAG analyzer imported from RAGFlow, supportingChineseandEnglish. Use-fineto output the fine-grained analyzer results."ik": Bilingual analyzer imported from ik-analyzer, supportingChineseandEnglish. Use-fineto output the fine-grained analyzer results."chinese": Simplified Chinese. Use-fineto output the fine-grained analyzer results."traditional": Traditional Chinese."japanese": Japanese."korean": Korean."ngram": N-gram."keyword": "noop" analyzer used for columns containing keywords only."sparsegram[-min[-max]][-fold]": Content-defined sparse n-grams of the whole value, indexed for regular expression search.mindefaults to3andmaxto12;foldadditionally stores the ASCII-lowercased form of every gram, which a case insensitive pattern needs. Chinese, Japanese and Korean values also get one and two character grams, so a single character or a two character word narrows as well. Build the index withIndexInfo.sparsegram().
- Parameter settings for a secondary index:
No parameters are required. For now, use an empty list[]. - Parameter settings for a BMP index:
block_size: Optional - The size of the block in a BMP index. Range:"1"~"256". Defaults to"16"."compress_type": Optional"compress": (Default) Store the block-max index in sparse format. Works best with small block size situations."raw": Store the block-max index without compression.
- Parameter settings for an HNSW index:
A full-text index built with the sparsegram analyzer makes regex(column, pattern) filters use the index: the literals the pattern proves mandatory are turned into gram lookups first, and the regular expression then verifies the candidates that survive, so a pattern with literals only reads a fraction of the table. The predicate is written exactly as before.
from infinity import index
from infinity.filter_utils import regex_filter
# A full-text index only sees the rows that exist when it is built, so insert
# first. A regular analyzer serves keyword search, the sparse gram one `regex()`.
table_object.insert([{"id": 1, "doc": "harmful chemical reaction"}])
table_object.create_index(
"idx_doc",
index.IndexInfo("doc", index.IndexType.FullText, {"analyzer": "standard"}),
)
table_object.create_index(
"idx_doc_sg", index.IndexInfo.sparsegram("doc", fold_case=True)
)
table_object.filter(regex_filter("doc", r"(?i)colou?r of the (sky|sea)")).output(
["id", "doc"]
).to_pl()
A column without such an index keeps a plain scan, and a pattern that requires no literal (for example [0-9]+) does too. fold_case=True is what lets a pattern such as (?i)nobel prize use the index; a case sensitive pattern works either way.
When a column carries more than one full-text index, the choice is made per predicate: a filter_fulltext or a MATCH TEXT that names no index uses the column's regular analyzer index, while the narrowing added for regex() goes to the sparse gram index. An index can be named explicitly too, as in filter_fulltext('doc@idx_doc_sg', 'harmful chemical', 'operator=and').
In a SEARCH statement the regular expression is evaluated as the search's own filter. ORDER BY is a modifier of a search result and cannot appear in the same SELECT as SEARCH, so a sorted search has to be written as a subquery.
Import the infinity.index package to set IndexInfo, and IndexType.
from infinity.index import IndexInfo, IndexType
conflict_type: ConflictType, Optional
Error: Raise an error if an index with the same name exists.Ignore: Ignore the index creation request and keep the existing table with the same name.
You may want to import the infinity.common package to set ConflictType:
from infinity.common import ConflictType
If ConflictType is not set, it defaults to Error.
comment: str, Optional
Additional comment for the index to create.
Returns
A structure containing these attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.
Examples
Create an HNSW index on a dense vector column
from infinity.index import IndexInfo, IndexType
# Create a table named "test_index_hnsw" with a 1024-dimensional float vector column "c1"
table_object = db_object.create_table(
"test_index_hnsw", {"c1": {"type": "vector,1024,float"}}
)
# Create an HNSW index named "my_index" on column "c1" with default parameter settings:
# - "M": "16",
# - "ef_construction": "50",
# - "encode": "plain"
# Only the "metric" parameter (required) is explicitly set to L2 distance.
table_object.create_index(
"my_index", IndexInfo("c1", IndexType.Hnsw, {"metric": "l2"}), comment="Index One"
)
from infinity.index import IndexInfo, IndexType
# Create a table named "test_index_hnsw" with a 1024-dimensional float vector column "c1"
table_object = db_object.create_table(
"test_index_hnsw", {"c1": {"type": "vector,1024,float"}}
)
# Create an HNSW index named "my_index" on column "c1"
# Settings for "M", "ef_construction", and "metric" are the same as above, except:
# "encoding" is set to "lvq"
table_object.create_index(
"my_index",
IndexInfo(
"c1",
IndexType.Hnsw,
{"M": "16", "ef_construction": "50", "metric": "l2", "encode": "lvq"},
),
)
Create an HNSW index on a multi-vector column
from infinity.index import IndexInfo, IndexType
# Create a table named "test_index_hnsw" with a 4-dimensional float multivector column "c1"
table_object = db_object.create_table(
"test_index_hnsw", {"c1": {"type": "multivector,4,float"}}
)
# Create an HNSW index named "my_index" on column "c1" with default parameter settings:
# - "M": "16",
# - "ef_construction": "50",
# - "encode": "plain"
# Only the "metric" parameter (required) is explicitly set to L2 distance.
table_object.create_index("my_index", IndexInfo("c1", IndexType.Hnsw, {"metric": "l2"}))
Create a full-text index
from infinity.index import IndexInfo, IndexType
# Create a table named "test_index_fulltext" with a varchar column "body"
table_object = db_object.create_table(
"test_index_fulltext", {"body": {"type": "varchar"}}
)
# Create a full-text index named "my_index" on column "body" with default parameter settings:
# - "ANALYZER": "standard"
table_object.create_index(
"my_index",
IndexInfo(
"body",
IndexType.FullText,
),
)
from infinity.index import IndexInfo, IndexType
# Create a table named "test_index_fulltext" with a varchar column "body"
table_object = db_object.create_table(
"test_index_fulltext", {"body": {"type": "varchar"}}
)
# Create a full-text index named "my_index" on column "body"
# Setting "ANALYZER" to "standard" (same as the above)
table_object.create_index(
"my_index", IndexInfo("body", IndexType.FullText, {"ANALYZER": "standard"})
)
Create a secondary index
from infinity.index import IndexInfo, IndexType
# Create a table named "test_index_secondary" with a varchar column "body"
table_object = db_object.create_table(
"test_index_secondary", {"c1": {"type": "varchar"}}
)
# Create a secondary index named "my_index" on column "c1"
table_object.create_index("my_index", IndexInfo("c1", IndexType.Secondary))
Create a BMP index
from infinity.index import IndexInfo, IndexType
# Create a table named "test_index_bmp" with a sparse vector column "c1"
table_object = db_object.create_table(
"test_index_bmp", {"c1": {"type": "sparse,30000,float,int16"}}
)
# Create a BMP index named "my_index" on column "c1" with default parameter settings:
# - "block_size": "16"
# - "compress_type": "compress"
table_object.create_index("my_index", IndexInfo("c1", IndexType.BMP))
from infinity.index import IndexInfo, IndexType
# Create a table named "test_index_bmp" with a sparse vector column "c1"
table_object = db_object.create_table(
"test_index_bmp", {"c1": {"type": "sparse,30000,float,int16"}}
)
# Create a BMP index named "my_index" on column "c1"
# Settings for "block_size" and "compress_type" are the same as above
table_object.create_index(
"my_index",
IndexInfo("c1", IndexType.BMP, {"block_size": "16", "compress_type": "compress"}),
)
optimize_index
table_obj.optimize()
Optimize all indexes in a table.
Returns
A structure containing the following attributes:
error_code:int0: The operation succeeds.- A non-zero value indicates a specific error condition.
error_msg:str
Whenerror_codeis non-zero,error_msgprovides additional details about the error.