API Reference

This section contains the complete API reference for the LanceDB C library, automatically generated from the header file comments.

Complete API

Typedefs

typedef struct LanceDBConnectBuilder LanceDBConnectBuilder

Opaque handle to a LanceDB ConnectBuilder.

typedef struct LanceDBConnection LanceDBConnection

Opaque handle to a LanceDB Connection.

typedef struct LanceDBTable LanceDBTable

Opaque handle to a LanceDB Table.

typedef struct LanceDBTableNamesBuilder LanceDBTableNamesBuilder

Opaque handle to a LanceDB TableNamesBuilder.

typedef struct LanceDBQuery LanceDBQuery

Opaque handle to a LanceDB Query.

typedef struct LanceDBVectorQuery LanceDBVectorQuery

Opaque handle to a LanceDB VectorQuery.

typedef struct LanceDBQueryResult LanceDBQueryResult

Opaque handle to a LanceDB QueryResult.

typedef struct LanceDBRecordBatchReader LanceDBRecordBatchReader

Opaque handle to Arrow RecordBatchReader.

typedef struct FFI_ArrowSchema FFI_ArrowSchema

Arrow C ABI Schema structure (opaque)

typedef struct FFI_ArrowArray FFI_ArrowArray

Arrow C ABI Array structure (opaque)

Enums

enum LanceDBError

Error codes for LanceDB C API.

Values:

enumerator LANCEDB_SUCCESS
enumerator LANCEDB_INVALID_ARGUMENT
enumerator LANCEDB_INVALID_TABLE_NAME
enumerator LANCEDB_INVALID_INPUT
enumerator LANCEDB_TABLE_NOT_FOUND
enumerator LANCEDB_DATABASE_NOT_FOUND
enumerator LANCEDB_DATABASE_ALREADY_EXISTS
enumerator LANCEDB_INDEX_NOT_FOUND
enumerator LANCEDB_EMBEDDING_FUNCTION_NOT_FOUND
enumerator LANCEDB_TABLE_ALREADY_EXISTS
enumerator LANCEDB_CREATE_DIR
enumerator LANCEDB_SCHEMA
enumerator LANCEDB_RUNTIME
enumerator LANCEDB_TIMEOUT
enumerator LANCEDB_OBJECT_STORE
enumerator LANCEDB_LANCE
enumerator LANCEDB_HTTP
enumerator LANCEDB_RETRY
enumerator LANCEDB_ARROW
enumerator LANCEDB_NOT_SUPPORTED
enumerator LANCEDB_OTHER
enumerator LANCEDB_UNKNOWN
enum LanceDBDistanceType

Distance type enum for vector search.

Values:

enumerator LANCEDB_DISTANCE_L2
enumerator LANCEDB_DISTANCE_COSINE
enumerator LANCEDB_DISTANCE_DOT
enumerator LANCEDB_DISTANCE_HAMMING
enum LanceDBIndexType

Index type enum.

Values:

enumerator LANCEDB_INDEX_AUTO
enumerator LANCEDB_INDEX_BTREE
enumerator LANCEDB_INDEX_BITMAP
enumerator LANCEDB_INDEX_LABELLIST
enumerator LANCEDB_INDEX_FTS
enumerator LANCEDB_INDEX_IVF_FLAT
enumerator LANCEDB_INDEX_IVF_PQ
enumerator LANCEDB_INDEX_IVF_HNSW_PQ
enumerator LANCEDB_INDEX_IVF_HNSW_SQ
enum LanceDBOptimizeType

Optimize type enum.

Values:

enumerator LANCEDB_OPTIMIZE_ALL
enumerator LANCEDB_OPTIMIZE_COMPACT
enumerator LANCEDB_OPTIMIZE_PRUNE
enumerator LANCEDB_OPTIMIZE_INDEX

Functions

static const char *lancedb_error_to_message(LanceDBError error)

Convert error code to error message.

The returned string is valid for the lifetime of the program. The caller must not free the returned string.

Parameters:

error – - error code

Returns:

Pointer to null-terminated C string containing the error message

LanceDBConnectBuilder *lancedb_connect(const char *uri)

Create a ConnectBuilder for the given URI.

The URI can be:

  • ”/path/to/database” - local database on file system

  • ”s3://bucket/path/to/database” or “gs://bucket/path/to/database” - database on cloud object store

  • ”db://dbname” - LanceDB Cloud

The returned pointer must be freed with lancedb_connect_builder_free().

Parameters:

uri – - null-terminated C string containing the database URI

Returns:

Non-null pointer to LanceDBConnectBuilder on success, NULL on failure

LanceDBConnection *lancedb_connect_builder_execute(LanceDBConnectBuilder *builder)

Execute the connection and return a Connection handle.

On success, the builder is consumed by this function and must not be used after calling. The returned connection must be freed with lancedb_connection_free().

Parameters:

builder – - pointer to LanceDBConnectBuilder returned from lancedb_connect()

Returns:

Non-null pointer to LanceDBConnection on success, NULL on failure

LanceDBConnectBuilder *lancedb_connect_builder_storage_option(LanceDBConnectBuilder *builder, const char *key, const char *value)

Set an option for the storage layer.

The builder is consumed by this function and must not be used after calling.

The key and value are going through basic validation at this point, and error will happen when trying to execute a builder with unsupported key or value.

Parameters:

  • builder – - pointer to LanceDBConnectBuilder returned from lancedb_connect()

  • key – - null-terminated C string containing the name of the option

  • value – - null-terminated C string containing the value of the option

Returns:

Non-null pointer to LanceDBConnectBuilder on success, NULL on failure

void lancedb_connect_builder_free(LanceDBConnectBuilder *builder)

Free a ConnectBuilder.

After calling this function, the builder pointer must not be used.

Parameters:

builder – - pointer to LanceDBConnectBuilder returned from lancedb_connect()

const char *lancedb_connection_uri(const LanceDBConnection *connection)

Get the URI of the connection.

The returned string is valid until the connection is freed. The caller must not free the returned string.

Parameters:

connection – - pointer to LanceDBConnection

Returns:

Pointer to null-terminated C string containing the URI, or NULL on failure

LanceDBError lancedb_connection_table_names(const LanceDBConnection *connection, char ***names_out, size_t *count_out, char **error_message)

Get table names from the connection.

The caller is responsible for freeing the returned strings and array using lancedb_free_table_names(). If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • connection – - pointer to LanceDBConnection

  • names_out – - pointer to receive array of string pointers

  • count_out – - pointer to receive count of table names

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

void lancedb_free_table_names(char **names, size_t count)

Free table names array returned by lancedb_connection_table_names.

Parameters:

  • names – - array of string pointers returned by lancedb_connection_table_names

  • count – - number of strings in the array

LanceDBTableNamesBuilder *lancedb_connection_table_names_builder(const LanceDBConnection *connection)

Create a TableNamesBuilder for paginated table listing.

The returned pointer must be freed with lancedb_table_names_builder_free(). Use lancedb_table_names_builder_limit() and lancedb_table_names_builder_start_after() to configure pagination before calling lancedb_table_names_builder_execute().

Parameters:

connection – - pointer to LanceDBConnection

Returns:

Non-null pointer to LanceDBTableNamesBuilder on success, NULL on failure

LanceDBTableNamesBuilder *lancedb_table_names_builder_limit(LanceDBTableNamesBuilder *builder, unsigned int limit)

Set limit on TableNamesBuilder.

The builder is consumed by this function and must not be used after calling.

Parameters:

  • builder – - pointer to LanceDBTableNamesBuilder

  • limit – - maximum number of table names to return

Returns:

Non-null pointer to LanceDBTableNamesBuilder on success, NULL on failure

LanceDBTableNamesBuilder *lancedb_table_names_builder_start_after(LanceDBTableNamesBuilder *builder, const char *start_after)

Set start_after on TableNamesBuilder for pagination.

The builder is consumed by this function and must not be used after calling. This is used for pagination - returns table names alphabetically after the specified name.

Parameters:

  • builder – - pointer to LanceDBTableNamesBuilder

  • start_after – - null-terminated C string containing the table name to start after

Returns:

Non-null pointer to LanceDBTableNamesBuilder on success, NULL on failure

LanceDBError lancedb_table_names_builder_execute(LanceDBTableNamesBuilder *builder, char ***names_out, size_t *count_out, char **error_message)

Execute TableNamesBuilder and return table names.

The builder is consumed by this function and must not be used after calling. The caller is responsible for freeing the returned strings and array using lancedb_free_table_names(). If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • builder – - pointer to LanceDBTableNamesBuilder (consumed by this function)

  • names_out – - pointer to receive array of string pointers

  • count_out – - pointer to receive count of table names

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

void lancedb_table_names_builder_free(LanceDBTableNamesBuilder *builder)

Free a TableNamesBuilder.

After calling this function, the builder pointer must not be used.

Parameters:

builder – - pointer to LanceDBTableNamesBuilder

LanceDBTable *lancedb_connection_open_table(const LanceDBConnection *connection, const char *table_name)

Open an existing table.

The returned table must be freed with lancedb_table_free().

Parameters:

  • connection – - pointer to LanceDBConnection

  • table_name – - null-terminated C string containing the table name

Returns:

Non-null pointer to LanceDBTable on success, NULL on failure

LanceDBError lancedb_connection_drop_table(const LanceDBConnection *connection, const char *table_name, const char *_namespace, char **error_message)

Drop a table from the database.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • connection – - pointer to LanceDBConnection

  • table_name – - null-terminated C string containing the table name

  • _namespace – - null-terminated C string containing the namespace (NULL for no namespace)

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_connection_rename_table(const LanceDBConnection *connection, const char *old_name, const char *new_name, const char *cur_namespace, const char *new_namespace, char **error_message)

Rename a table in the database.

This operation is only supported in LanceDB Cloud. If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • connection – - pointer to LanceDBConnection

  • old_name – - null-terminated C string containing the current table name

  • new_name – - null-terminated C string containing the new table name

  • cur_namespace – - null-terminated C string containing the current namespace (NULL for no namespace)

  • new_namespace – - null-terminated C string containing the new namespace (NULL for no namespace)

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_connection_drop_all_tables(const LanceDBConnection *connection, const char *_namespace, char **error_message)

Drop all tables in the database.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • connection – - pointer to LanceDBConnection

  • _namespace – - null-terminated C string containing the namespace (NULL for no namespace)

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_connection_create_namespace(const LanceDBConnection *connection, const char *namespace_name, char **error_message)

Create a new namespace.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • connection – - pointer to LanceDBConnection

  • namespace_name – - null-terminated C string containing the namespace name

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_connection_drop_namespace(const LanceDBConnection *connection, const char *namespace_name, char **error_message)

Drop a namespace.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • connection – - pointer to LanceDBConnection

  • namespace_name – - null-terminated C string containing the namespace name

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_connection_list_namespaces(const LanceDBConnection *connection, const char *namespace_parent, char ***namespaces_out, size_t *count_out, char **error_message)

List all namespaces in the database.

The caller is responsible for freeing the returned strings and array using lancedb_free_namespace_list(). If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • connection – - pointer to LanceDBConnection

  • namespace_parent – - null-terminated C string containing the parent namespace (NULL for root)

  • namespaces_out – - pointer to receive array of string pointers

  • count_out – - pointer to receive count of namespace names

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

void lancedb_free_namespace_list(char **namespaces, size_t count)

Free namespace list array returned by lancedb_connection_list_namespaces.

After calling this function, the namespaces pointer must not be used.

Parameters:
void lancedb_connection_free(LanceDBConnection *connection)

Free a Connection.

After calling this function, the connection pointer must not be used.

Parameters:

connection – - pointer to LanceDBConnection returned from lancedb_connect_builder_execute()

void lancedb_table_free(LanceDBTable *table)

Free a Table.

After calling this function, the table pointer must not be used.

Parameters:

table – - pointer to LanceDBTable returned from lancedb_connection_open_table()

LanceDBError lancedb_table_create(const LanceDBConnection *connection, const char *table_name, const FFI_ArrowSchema *schema_ptr, LanceDBRecordBatchReader *reader, LanceDBTable **table_out, char **error_message)

Create a new table with Arrow schema.

The caller is responsible for freeing the returned table with lancedb_table_free(). If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • connection – - pointer to LanceDBConnection

  • table_name – - null-terminated C string containing the table name

  • schema_ptr – - pointer to Arrow C ABI schema

  • reader – - pointer to LanceDBRecordBatchReader or NULL for empty table

  • table_out – - pointer to receive the created table

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_table_arrow_schema(const LanceDBTable *table, FFI_ArrowSchema **schema_out, char **error_message)

Get table schema as Arrow C ABI.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • schema_out – - pointer to receive the Arrow schema

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure Caller is responsible for releasing the schema using Arrow C ABI

unsigned long long lancedb_table_version(const LanceDBTable *table)

Get table version.

Parameters:

table – - pointer to LanceDBTable

Returns:

Table version number on success, 0 on failure

unsigned long long lancedb_table_count_rows(const LanceDBTable *table)

Count rows in table.

Parameters:

table – - pointer to LanceDBTable

Returns:

Number of rows in table on success, 0 on failure (or empty table)

LanceDBError lancedb_table_add(const LanceDBTable *table, LanceDBRecordBatchReader *reader, char **error_message)

Add data to table using Arrow RecordBatchReader.

This function takes ownership of the reader and frees it automatically. Do NOT call lancedb_record_batch_reader_free() after calling this function. If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • reader – - pointer to LanceDBRecordBatchReader

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_table_merge_insert(const LanceDBTable *table, LanceDBRecordBatchReader *data, const char *const *on_columns, size_t num_columns, const LanceDBMergeInsertConfig *config, char **error_message)

Merge insert data into table (upsert operation)

This function performs an upsert operation by joining on the specified columns. New records are inserted, existing records can be updated based on configuration. This function takes ownership of the reader and frees it automatically. Do NOT call lancedb_record_batch_reader_free() after calling this function. If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • data – - pointer to LanceDBRecordBatchReader containing data to merge

  • on_columns – - array of column names to join on (typically key/id columns)

  • num_columns – - number of columns in the on_columns array

  • config – - pointer to LanceDBMergeInsertConfig for operation behavior (NULL for defaults)

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_table_delete(const LanceDBTable *table, const char *predicate, char **error_message)

Delete rows from table based on predicate.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • predicate – - null-terminated C string containing SQL WHERE clause

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBQuery *lancedb_query_new(const LanceDBTable *table)

Create a new query for the given table.

Parameters:

table – - pointer to LanceDBTable

Returns:

Pointer to LanceDBQuery on success, NULL on failure Caller must free with lancedb_query_free()

LanceDBVectorQuery *lancedb_vector_query_new(const LanceDBTable *table, const float *vector, size_t dimension)

Create a vector query from table with query vector.

Parameters:

  • table – - pointer to LanceDBTable

  • vector – - array of floats representing the query vector

  • dimension – - dimension of the vector

Returns:

Pointer to LanceDBVectorQuery on success, NULL on failure Caller must free with lancedb_vector_query_free()

LanceDBError lancedb_query_limit(LanceDBQuery *query, size_t limit, char **error_message)

Set limit for query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBQuery

  • limit – - maximum number of results

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_query_offset(LanceDBQuery *query, size_t offset, char **error_message)

Set offset for query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBQuery

  • offset – - number of results to skip

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_query_select(LanceDBQuery *query, const char *const *columns, size_t num_columns, char **error_message)

Set columns to select for query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBQuery

  • columns – - array of column name strings

  • num_columns – - number of columns

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_query_where_filter(LanceDBQuery *query, const char *filter, char **error_message)

Set WHERE filter for query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBQuery

  • filter – - SQL WHERE clause string

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_vector_query_limit(LanceDBVectorQuery *query, size_t limit, char **error_message)

Set limit for vector query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBVectorQuery

  • limit – - maximum number of results

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_vector_query_offset(LanceDBVectorQuery *query, size_t offset, char **error_message)

Set offset for vector query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBVectorQuery

  • offset – - number of results to skip

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_vector_query_column(LanceDBVectorQuery *query, const char *column, char **error_message)

Set vector column for vector query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBVectorQuery

  • column – - vector column name

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_vector_query_select(LanceDBVectorQuery *query, const char *const *columns, size_t num_columns, char **error_message)

Set columns to select for vector query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBVectorQuery

  • columns – - array of column name strings

  • num_columns – - number of columns

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_vector_query_where_filter(LanceDBVectorQuery *query, const char *filter, char **error_message)

Set WHERE filter for vector query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBVectorQuery

  • filter – - SQL WHERE clause string

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_vector_query_distance_type(LanceDBVectorQuery *query, LanceDBDistanceType distance_type, char **error_message)

Set distance type for vector query.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBVectorQuery

  • distance_type – - distance metric to use

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_vector_query_nprobes(LanceDBVectorQuery *query, size_t nprobes, char **error_message)

Set number of probes for vector query.

This parameter controls how many partitions to search in IVF (Inverted File) based indices such as IVF_FLAT, IVF_PQ, IVF_HNSW_PQ, and IVF_HNSW_SQ.

IVF indices partition the vector space into clusters. During search, nprobes determines how many of these partitions are searched. Higher values improve recall (find more relevant results) at the cost of slower queries. Lower values make queries faster but may miss relevant results that are in non-searched partitions.

Typical values:

  • Default is usually 20

  • Range: 1 to num_partitions (specified during index creation)

  • Higher nprobes (e.g., num_partitions/2) → better recall, slower queries

  • Lower nprobes (e.g., 1-10) → faster queries, lower recall

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBVectorQuery

  • nprobes – - number of IVF partitions to search (must be <= num_partitions)

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_vector_query_refine_factor(LanceDBVectorQuery *query, unsigned int refine_factor, char **error_message)

Set refine factor for vector query.

This parameter enables a refinement step to improve result accuracy for approximate vector indices (IVF_PQ, IVF_HNSW_PQ, IVF_HNSW_SQ).

When refine_factor is set, the search process works in two stages:

  1. Fetch (limit × refine_factor) approximate nearest neighbors using the index

  2. Re-rank these candidates using exact distance calculations on original vectors

  3. Return the top ‘limit’ results after refinement

This improves accuracy because approximate indices (especially quantized ones like PQ/SQ) can have ranking errors. Refinement corrects these errors by recalculating exact distances.

Typical values:

  • Default: No refinement (refine_factor = 1 or not set)

  • Range: 1 to ~100

  • refine_factor = 1 → no refinement (fastest, least accurate)

  • refine_factor = 10 → fetch 10x results and refine (good balance)

  • refine_factor = 50+ → very accurate but slower

Note: Higher values increase query latency proportionally. Not useful for exact indices like IVF_FLAT which already use exact distances.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBVectorQuery

  • refine_factor – - multiplier for candidate set size (fetches limit × refine_factor results)

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_vector_query_ef(LanceDBVectorQuery *query, size_t ef, char **error_message)

Set ef parameter for HNSW vector query.

This parameter controls the exploration factor for HNSW (Hierarchical Navigable Small World) based indices such as IVF_HNSW_PQ and IVF_HNSW_SQ.

HNSW is a graph-based index that navigates through a multi-layer graph to find nearest neighbors. The ‘ef’ parameter determines the size of the dynamic candidate list maintained during the graph traversal. A larger candidate list explores more of the graph, leading to better recall but slower queries.

How it works:

  • During search, HNSW maintains a priority queue of size ‘ef’ with candidate neighbors

  • The algorithm explores neighbors of candidates in this queue

  • Larger ef → explores more paths through the graph → better recall

  • After exploration, the top ‘limit’ results are returned

Typical values:

  • Default is usually 100

  • Must be >= limit (query result size)

  • Range: limit to ~1000

  • ef = limit → fastest, lowest recall

  • ef = 100-200 → good balance for most use cases

  • ef = 500+ → very high recall, slower queries

Note: The ef parameter at query time is different from ef_construction used during index building. Query-time ef controls search quality, while ef_construction controls index quality.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • query – - pointer to LanceDBVectorQuery

  • ef – - exploration factor for HNSW search (must be >= query limit)

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBQueryResult *lancedb_query_execute(LanceDBQuery *query)

Execute query and return streaming result.

Parameters:

query – - pointer to LanceDBQuery (consumed by this function)

Returns:

Pointer to LanceDBQueryResult on success, NULL on failure Caller must free with lancedb_query_result_free()

LanceDBQueryResult *lancedb_vector_query_execute(LanceDBVectorQuery *query)

Execute vector query and return streaming result.

Parameters:

query – - pointer to LanceDBVectorQuery (consumed by this function)

Returns:

Pointer to LanceDBQueryResult on success, NULL on failure Caller must free with lancedb_query_result_free()

LanceDBError lancedb_query_result_to_arrow(LanceDBQueryResult *result, struct FFI_ArrowArray ***result_arrays, struct FFI_ArrowSchema **result_schema, size_t *count_out, char **error_message)

Convert query result to Arrow RecordBatch arrays.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • result – - pointer to LanceDBQueryResult (consumed by this function)

  • result_arrays – - pointer to receive array of Arrow C ABI arrays

  • result_schema – - pointer to receive single Arrow C ABI schema

  • count_out – - pointer to receive number of result batches

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure Caller must free arrays with lancedb_free_arrow_arrays() and schema with lancedb_free_arrow_schema()

void lancedb_query_free(LanceDBQuery *query)

Free a Query.

Parameters:

query – - pointer to LanceDBQuery

void lancedb_vector_query_free(LanceDBVectorQuery *query)

Free a VectorQuery.

Parameters:

query – - pointer to LanceDBVectorQuery

void lancedb_query_result_free(LanceDBQueryResult *result)

Free a QueryResult.

Parameters:

result – - pointer to LanceDBQueryResult

LanceDBError lancedb_table_nearest_to(const LanceDBTable *table, const float *vector, size_t dimension, size_t limit, const char *column, struct FFI_ArrowArray ***result_arrays, struct FFI_ArrowSchema **result_schema, size_t *count_out, char **error_message)

Vector search using nearest_to with full result conversion.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • vector – - array of floats representing the query vector

  • dimension – - dimension of the vector

  • limit – - maximum number of results to return

  • column – - vector column name (NULL for default “vector” column)

  • result_arrays – - pointer to receive array of Arrow C ABI arrays

  • result_schema – - pointer to receive single Arrow C ABI schema (shared by all arrays)

  • count_out – - pointer to receive number of result batches

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure Caller must free arrays with lancedb_free_arrow_arrays() and schema with lancedb_free_arrow_schema()

LanceDBRecordBatchReader *lancedb_record_batch_reader_from_arrow(const struct FFI_ArrowArray *array, const struct FFI_ArrowSchema *schema)

Create a RecordBatchReader from Arrow C ABI structures.

This function consumes the array according to Arrow C ABI specification. The caller should NOT call the array’s release function after passing it here. The schema is only read and should still be released by the caller. The caller is responsible for freeing the returned reader with lancedb_record_batch_reader_free().

Parameters:

  • array – - pointer to FFI_ArrowArray containing record batch data

  • schema – - pointer to FFI_ArrowSchema containing the schema

Returns:

Pointer to LanceDBRecordBatchReader on success, NULL on failure

void lancedb_record_batch_reader_free(LanceDBRecordBatchReader *reader)

Free RecordBatchReader.

Parameters:

reader – - pointer to LanceDBRecordBatchReader

void lancedb_free_arrow_schema(FFI_ArrowSchema *schema)

Free Arrow schema.

Parameters:

schema – - pointer to Arrow schema

LanceDBError lancedb_table_create_vector_index(const LanceDBTable *table, const char *const *columns, size_t num_columns, LanceDBIndexType index_type, const LanceDBVectorIndexConfig *config, char **error_message)

Create a vector index on table columns.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • columns – - array of null-terminated C strings containing column names

  • num_columns – - number of columns in the array

  • index_type – - type of vector index to create

  • config – - pointer to LanceDBVectorIndexConfig or NULL for defaults

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_table_create_scalar_index(const LanceDBTable *table, const char *const *columns, size_t num_columns, LanceDBIndexType index_type, const LanceDBScalarIndexConfig *config, char **error_message)

Create a scalar index on table columns.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • columns – - array of null-terminated C strings containing column names

  • num_columns – - number of columns in the array

  • index_type – - type of scalar index to create

  • config – - pointer to LanceDBScalarIndexConfig or NULL for defaults

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_table_create_fts_index(const LanceDBTable *table, const char *const *columns, size_t num_columns, const LanceDBFtsIndexConfig *config, char **error_message)

Create a full-text search index on table columns.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • columns – - array of null-terminated C strings containing column names

  • num_columns – - number of columns in the array

  • config – - pointer to LanceDBFtsIndexConfig or NULL for defaults

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_table_list_indices(const LanceDBTable *table, char ***indices_out, size_t *count_out, char **error_message)

List all indices on the table.

The caller is responsible for freeing the returned strings and array using lancedb_free_index_list(). If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • indices_out – - pointer to receive array of index info strings

  • count_out – - pointer to receive the count of indices

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_table_drop_index(const LanceDBTable *table, const char *index_name, char **error_message)

Drop an index.

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • index_name – - null-terminated C string containing the index name

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

LanceDBError lancedb_table_optimize(const LanceDBTable *table, LanceDBOptimizeType optimize_type, char **error_message)

Optimize table (rebuild indices and compact files)

If error_message is provided and an error occurs, the caller must free the error message with lancedb_free_string().

Parameters:

  • table – - pointer to LanceDBTable

  • optimize_type – - type of optimization to perform

  • error_message – - optional pointer to receive detailed error message (NULL to ignore)

Returns:

Error code indicating success or failure

void lancedb_free_index_list(char **indices, size_t count)

Free index list array returned by lancedb_table_list_indices.

Parameters:

  • indices – - array of string pointers returned by lancedb_table_list_indices

  • count – - number of strings in the array

void lancedb_free_arrow_arrays(struct FFI_ArrowArray **arrays, size_t count)

Free Arrow arrays returned by vector search functions.

Parameters:

  • arrays – - array of Arrow C ABI array pointers

  • count – - number of arrays

void lancedb_free_string(char *str)

Free string returned by LanceDB functions.

Parameters:

str – - string pointer returned by LanceDB functions

Variables

static const char *LANCEDB_ERROR_MESSAGES[] = {"Success", "Invalid argument", "Invalid table name", "Invalid input", "Table not found", "Database not found", "Database already exists", "Index not found", "Embedding function not found", "Table already exists", "Failed to create directory", "Schema error", "Runtime error", "Operation timed out", "Object store error", "Lance format error", "HTTP error", "Retryable error", "Arrow error", "Operation not supported", "Other error", "Unknown error"}

Error messages for LanceDB C API.

struct LanceDBVectorIndexConfig
#include <lancedb.h>

Vector index configuration.

Public Members

int num_partitions
int num_sub_vectors
int max_iterations
float sample_rate
LanceDBDistanceType distance_type
const char *accelerator
int replace
struct LanceDBScalarIndexConfig
#include <lancedb.h>

Scalar index configuration.

Public Members

int replace
int force_update_statistics
struct LanceDBFtsIndexConfig
#include <lancedb.h>

Full-text search index configuration.

Public Members

const char *base_tokenizer
const char *language
int max_tokens
int lowercase
int stem
int remove_stop_words
int ascii_folding
int replace
struct LanceDBMergeInsertConfig
#include <lancedb.h>

Merge insert configuration.

Public Members

int when_matched_update_all
int when_not_matched_insert_all