orcalib#

EXACT_MATCH_THRESHOLD `module-attribute` #

EXACT_MATCH_THRESHOLD = 0.99999

Default threshold for exact match in Orca.

ColumnName `module-attribute` #

ColumnName = str

Column name type alias

RowDict `module-attribute` #

RowDict = dict[ColumnName, Any]

Row dictionary type alias

CatchupStatus #

Bases: str, Enum

Index status enum. Used to check the status of a catchup operation.

Attributes:

IN_PROGRESS –

Index is still catching up
COMPLETED –

Index has caught up
FAILED –

Catchup operation failed
CANCELLED –

Catchup operation was cancelled
CANCELLING –

Catchup operation is in the process of being cancelled

ImageFormat #

Bases: str, Enum

Image format enum. Used with the Image column type.

Attributes:

JPEG –

JPEG format
PNG –

PNG format
TIFF –

TIFF format
GIF –

GIF format
BMP –

BMP format

Order #

Bases: str, Enum

Specifies the order of a column in a query.

Attributes:

ASC –

Ascending order
DESC –

Descending order
DEFAULT –

Use the default order of the column

TableCreateMode #

Bases: str, Enum

Options for create_table if the table already exists

Attributes:

ERROR_IF_TABLE_EXISTS –

Raise exception if the table exists
REPLACE_CURR_TABLE –

Replace existing table with the same name
RETURN_CURR_TABLE –

Return the existing table when create_table is called

set_orca_credentials #

set_orca_credentials(*, api_key, secret_key, endpoint=None)

Set the credentials for the Orca client. This must be called before any other Orca functions. This can also be called multiple times to change the credentials.

Parameters:

api_key (str | None) –

API key
secret_key (str | None) –

Secret key
endpoint (str | None, default: None ) –

Endpoint (optional)

Examples:

>>> dotenv.load_dotenv()
>>> set_orca_credentials(
...     api_key=os.getenv("ORCADB_API_KEY"),
...     secret_key=os.getenv("ORCADB_SECRET_KEY"),
...     endpoint=os.getenv("ORCADB_ENDPOINT"),
... )

check_orca_version_compatibility #

1	`check_orca_version_compatibility()`

Check if the OrcaLib version is compatible with the OrcaDB instance version and log a warning if not.

Returns:

bool | None –

True if the versions match, False if they do not, None if the version check is skipped

Examples:

>>> check_orca_version_compatibility()

create_table #

create_table(
    db,
    table_name,
    if_table_exists=TableCreateMode.ERROR_IF_TABLE_EXISTS,
    **columns
)

Create a table in the default database. This is a convenience function that calls create_table on the default db.

Parameters:

table_name (str) –

Name of the table
if_table_exists (TableCreateMode, default: ERROR_IF_TABLE_EXISTS ) –

What to do if the table already exists
**columns (OrcaTypeHandle, default: {} ) –

Columns of the table (name -> type mapping)

Returns:

TableHandle –

TableHandle

Examples:

>>> import orcalib as orca
>>> orca.create_table("my_table", id=orca.Int64T, name=orca.TextT)

get_table #

get_table(db, table_name)

Get a table from the default database. This is a convenience function that calls get_table on the default db.

Parameters:

table_name (str) –

Name of the table

Returns:

TableHandle –

TableHandle

Examples:

>>> import orcalib as orca
>>> orca.get_table("my_table")

list_tables #

list_tables(db)

List tables in the default database. This is a convenience function that calls list_tables on the default db.

Returns:

list[str] –

List of table names

Examples:

>>> import orcalib as orca
>>> orca.list_tables()

backup #

backup(db)

Backup the default database. This is a convenience function that calls backup on the default db.

Returns:

tuple[str, str] –

Backup path and backup name

Examples:

>>> import orcalib as orca
>>> orca.backup()

get_index #

get_index(db, index_name)

Get an index from the default database. This is a convenience function that calls get_index on the default db.

Parameters:

index_name (str) –

Name of the index

Returns:

IndexHandle –

IndexHandle

Examples:

>>> import orcalib as orca
>>> index_handle = orca.get_index("my_index")

create_vector_index #

create_vector_index(
    db, index_name, table_name, column, error_if_exists=True
)

Create a vector index for default db. This is a convenience function that calls create_vector_index on the default db.

Parameters:

index_name (str) –

Name of the index
table_name (str) –

Name of the table
column (str) –

Name of the column
error_if_exists (bool, default: True ) –

Whether to raise an error if the index already exists

create_document_index #

create_document_index(
    db, index_name, table_name, column, error_if_exists=True
)

Create a document index for default db. This is a convenience function that calls create_document_index on the default db.

Parameters:

index_name (str) –

Name of the index
table_name (str) –

Name of the table
column (str) –

Name of the column
error_if_exists (bool, default: True ) –

Whether to raise an error if the index already exists (default: True)

Examples:

>>> import orcalib as orca
>>> orca.create_document_index("my_index", "my_table", "my_column")

create_text_index #

create_text_index(
    db, index_name, table_name, column, error_if_exists=True
)

Create a text index for default db. This is a convenience function that calls create_text_index on the default db.

Parameters:

index_name (str) –

Name of the index
table_name (str) –

Name of the table
column (str) –

Name of the column
error_if_exists (bool, default: True ) –

Whether to raise an error if the index already exists (default: True)

Examples:

>>> import orcalib as orca
>>> orca.create_text_index("my_index", "my_table", "my_column")

create_btree_index #

create_btree_index(
    db, index_name, table_name, column, error_if_exists=True
)

Create a btree index for default db. This is a convenience function that calls create_btree_index on the default db.

Parameters:

index_name (str) –

Name of the index
table_name (str) –

Name of the table
column (str) –

Name of the column
error_if_exists (bool, default: True ) –

Whether to raise an error if the index already exists

Examples:

>>> import orcalib as orca
>>> orca.create_btree_index("my_index", "my_table", "my_column")

drop_index #

drop_index(db, index_name, error_if_not_exists=True)

Drop an index from the default database. This is a convenience function that calls drop_index on the default db.

Parameters:

index_name (str) –

Name of the index
error_if_not_exists (bool, default: True ) –

Whether to raise an error if the index does not exist

Examples:

>>> import orcalib as orca
>>> orca.drop_index("my_index")

drop_table #

drop_table(db, table_name, error_if_not_exists=True)

Drop a table from the default database. This is a convenience function that calls drop_table on the default db.

Parameters:

table_name (str) –

Name of the table
error_if_not_exists (bool, default: True ) –

Whether to raise an error if the table does not exist

Examples:

>>> import orcalib as orca
>>> orca.drop_table("my_table")

search_memory #

search_memory(db, index_name, query, limit, columns=None)

Search memory for default db. This is a convenience function that calls search_memory on the default db.

Parameters:

index_name (str) –

Name of the index
query (list[float]) –

Query
limit (int) –

Limit
columns (list[str] | None, default: None ) –

Columns to return (optional)

Examples:

>>> import orcalib as orca
>>> orca.search_memory("my_index", [1.0, 2.0], 10)

scan_index #

scan_index(db, index_name, query)

Scan an index for default db. This is a convenience function that calls scan_index on the default db.

Parameters:

index_name (str) –

Name of the index
query (Any) –

Query

Returns:

DefaultIndexQuery –

DefaultIndexQuery

Examples:

>>> import orcalib as orca
>>> orca.scan_index("my_index", orca.OrcaExpr("$EQ", (orca.ColumnHandle("my_table", "my_column"), 42)))

vector_scan_index #

vector_scan_index(db, index_name, query)

Scan a vector index for default db. This is a convenience function that calls vector_scan_index on the default db.

Parameters:

index_name (str) –

Name of the index
query (Any) –

Query

Returns:

VectorIndexQuery –

VectorIndexQuery

Examples:

>>> import orcalib as orca
>>> orca.vector_scan_index("my_index", orca.OrcaExpr("$EQ", (orca.ColumnHandle("my_table", "my_column"), 42)))

full_vector_memory_join #

full_vector_memory_join(
    db,
    *,
    index_name,
    memory_index_name,
    num_memories,
    query_columns,
    page_index,
    page_size
)

Join a vector index with a memory index for default db. This is a convenience function that calls full_vector_memory_join on the default db.

Parameters:

index_name (str) –

Name of the index
memory_index_name (str) –

Name of the memory index
num_memories (int) –

Number of memories
query_columns (list[str]) –

Query columns
page_index (int) –

Page index
page_size (int) –

Page size

Returns:

dict[str, list[tuple[list[float], Any]]] –

Results

Examples:

>>> import orcalib as orca
>>> orca.full_vector_memory_join("my_index", "my_memory_index", 10, ["my_column"], 0, 10)

query #

query(db, query, params=[])

Execute a raw SQL query. This is a convenience function that calls query on the default db.

Parameters:

query (str) –

Query
params (list[None | int | float | bytes | str], default: [] ) –

Parameters

Returns:

DataFrame –

the query result in a DataFrame

Examples:

>>> import orcalib as orca
>>> orca.query("SELECT text, label FROM my_table")
DataFrame(
    text    | label
    "hello" | 1
    "world" | 2
)

orcalib#

EXACT_MATCH_THRESHOLD module-attribute #

ColumnName module-attribute #

RowDict module-attribute #

CatchupStatus #

ImageFormat #

Order #

TableCreateMode #

set_orca_credentials #

check_orca_version_compatibility #

create_table #

get_table #

list_tables #

backup #

get_index #

create_vector_index #

create_document_index #

create_text_index #

create_btree_index #

drop_index #

drop_table #

search_memory #

scan_index #

vector_scan_index #

full_vector_memory_join #

query #

EXACT_MATCH_THRESHOLD `module-attribute` #

ColumnName `module-attribute` #

RowDict `module-attribute` #