Python API

The reference for the completype package, generated from its typed stubs: __init__.pyi, completype.pyi and _async.pyi. Every name on this page is importable from completype.

Databases

connect

connect(
    url: str,
    options: Mapping[str, str] | None = None,
    cache_dir: str | PathLike[str] | None = None,
    **build_options,
) -> Database

Opens the database at url: a local path, or an s3://, gs://, az:// or memory:// URL.

connect(url, ...) is Database(url, ...): it takes url, options, cache_dir and the build options min_word_chars, max_edit_distance, fuzzy_prefix_chars, vector_bits, compact_keys and build_threads. See Configuration.

Database

Database(
    url: str,
    options: Mapping[str, str] | None = None,
    cache_dir: str | PathLike[str] | None = None,
    *,
    tags: Mapping[str, str] | None = None,
    min_word_chars: int = 3,
    max_edit_distance: int = 2,
    fuzzy_prefix_chars: int = 7,
    vector_bits: int = 4,
    compact_keys: bool = False,
    build_threads: int = 1,
)

namespace

namespace(name: str) -> DatabaseNamespace

Namespace name: 1 to 128 letters, digits, '.', '_' or '-'. Does no I/O.

namespaces

namespaces(version: int | None = None) -> list[str]

versions

versions() -> list[int]

latest_version

latest_version() -> int

index_names

index_names(version: int | None = None) -> list[str]

Indexes of the default namespace.

manifest

manifest(version: int | None = None) -> dict[str, Any]

begin

begin(version: int | None = None) -> Transaction

open_index

open_index(
    name: str,
    version: int | None = None,
    *,
    max_score: float | None = None,
    popularity_weight: float = 0.4,
    short_query_chars: int = 3,
    short_query_limit: int = 100,
    short_query_cache_entries: int = 10000,
    vector_threads: int = 1,
) -> Index

engine

engine(
    *,
    sync_every: float | None = 5.0,
    overfetch: int = 2,
    popularity_weight: float = 0.4,
    short_query_chars: int = 3,
    short_query_limit: int = 100,
    short_query_cache_entries: int = 10000,
    vector_threads: int = 1,
) -> Engine

compact

compact(
    index: str,
    *,
    fanout: int = 4,
    max_segments: int = 16,
    max_hidden_fraction: float = 0.25,
    until_done: bool = False,
) -> int | None

cleanup

cleanup(
    *,
    keep_versions: int = 10,
    older_than_seconds: float = 3600.0,
) -> dict[str, int]

acquire_lease

acquire_lease(
    name: str, owner: str, ttl_seconds: float
) -> Lease | None

submit

submit(changes: ChangeSet) -> str

pending_change_sets

pending_change_sets() -> int

DatabaseNamespace

One namespace of a Database: its transactions, indexes and compaction.

name property

name: str

index_names

index_names(version: int | None = None) -> list[str]

begin

begin(version: int | None = None) -> Transaction

open_index

open_index(
    name: str,
    version: int | None = None,
    *,
    max_score: float | None = None,
    popularity_weight: float = 0.4,
    short_query_chars: int = 3,
    short_query_limit: int = 100,
    short_query_cache_entries: int = 10000,
    vector_threads: int = 1,
) -> Index

compact

compact(
    index: str,
    *,
    fanout: int = 4,
    max_segments: int = 16,
    max_hidden_fraction: float = 0.25,
    until_done: bool = False,
) -> int | None

Transaction

As a context manager, commits on success and discards its changes on an exception.

read_version property

read_version: int

namespace

namespace(name: str) -> NamespaceTransaction

append

append(
    index: str,
    documents: Documents,
    deletes: Sequence[Id] = ...,
    vectors: Vectors | None = None,
) -> None

overwrite

overwrite(
    index: str,
    documents: Documents,
    vectors: Vectors | None = None,
) -> None

drop_index

drop_index(index: str) -> None

set_max_score

set_max_score(index: str, max_score: float) -> None

set_metadata

set_metadata(key: str, value: str | None) -> None

strict

strict(strict: bool = True) -> None

max_retries

max_retries(retries: int) -> None

commit

commit() -> dict[str, Any]

NamespaceTransaction

The index operations of a Transaction in one namespace.

name property

name: str

append

append(
    index: str,
    documents: Documents,
    deletes: Sequence[Id] = ...,
    vectors: Vectors | None = None,
) -> None

overwrite

overwrite(
    index: str,
    documents: Documents,
    vectors: Vectors | None = None,
) -> None

drop_index

drop_index(index: str) -> None

set_max_score

set_max_score(index: str, max_score: float) -> None

Lease

generation property

generation: int

renew

renew(ttl_seconds: float) -> bool

release

release() -> None

Store

Store(
    url: str,
    options: Mapping[str, str] | None = None,
    cache_dir: str | PathLike[str] | None = None,
    *,
    tags: Mapping[str, str] | None = None,
)

prune_cache

prune_cache(keep: Sequence[str]) -> int

get

get(key: str) -> bytes

put

put(key: str, data: bytes) -> None

put_if_absent

put_if_absent(key: str, data: bytes) -> bool

delete

delete(key: str) -> None

list

list(prefix: str = '') -> list[str]

put_segment

put_segment(key: str, segment: Segment) -> None

get_segment

get_segment(key: str) -> Segment

Indexes and engines

Index

Index(
    segments: Sequence[Segment],
    *,
    max_score: float | None = None,
    popularity_weight: float = 0.4,
    short_query_chars: int = 3,
    short_query_limit: int = 100,
    short_query_cache_entries: int = 10000,
    vector_threads: int = 1,
)

vector_dim property

vector_dim: int | None

max_score property

max_score: float

from_documents staticmethod

from_documents(
    documents: Documents,
    vectors: Vectors | None = None,
    *,
    max_score: float | None = None,
    popularity_weight: float = 0.4,
    min_word_chars: int = 3,
    max_edit_distance: int = 2,
    fuzzy_prefix_chars: int = 7,
    vector_bits: int = 4,
    build_threads: int = 1,
) -> Index

complete

complete(
    query: str,
    limit: int = 10,
    *,
    contexts: Sequence[str] | None = None,
) -> list[Suggestion]

complete_aliases

complete_aliases(
    query: str,
    limit: int = 10,
    *,
    contexts: Sequence[str] | None = None,
) -> list[AliasSuggestion]

vector_search

vector_search(
    vector: Vector,
    limit: int = 10,
    *,
    contexts: Sequence[str] | None = None,
) -> list[Suggestion]

hybrid_search

hybrid_search(
    text: str,
    vector: Vector,
    limit: int = 10,
    *,
    fusion: FusionKind = "rrf",
    rrf_k: float = 60.0,
    semantic_weight: float = 0.5,
    candidates: int | None = None,
    contexts: Sequence[str] | None = None,
) -> list[HybridSuggestion]

get

get(id: Id) -> Document | None

compact

compact(
    path: str | PathLike[str] | None = None,
    build_threads: int = 1,
) -> Segment

segments

segments() -> list[Segment]

Segment

vector_dim property

vector_dim: int | None

size_bytes property

size_bytes: int

build staticmethod

build(
    documents: Documents,
    deletes: Sequence[Id] = ...,
    vectors: Vectors | None = None,
    *,
    min_word_chars: int = 3,
    max_edit_distance: int = 2,
    fuzzy_prefix_chars: int = 7,
    vector_bits: int = 4,
    compact_keys: bool = False,
    build_threads: int = 1,
    path: str | PathLike[str] | None = None,
) -> Segment

open staticmethod

open(path: str | PathLike[str]) -> Segment

from_bytes staticmethod

from_bytes(data: bytes) -> Segment

verify

verify() -> None

to_bytes

to_bytes() -> bytes

save

save(path: str | PathLike[str]) -> None

documents

documents() -> list[Document]

ids

ids() -> list[int]

deletes

deletes() -> list[int]

SegmentWriter

SegmentWriter(
    directory: str | PathLike[str],
    *,
    memory_budget: int = ...,
    min_word_chars: int = 3,
    max_edit_distance: int = 2,
    fuzzy_prefix_chars: int = 7,
    vector_bits: int = 4,
    compact_keys: bool = False,
    build_threads: int = 1,
)

Writes segment files into directory, a new one whenever building would exceed memory_budget bytes.

add

add(documents: DocumentDict | Document | Documents) -> None

finish

finish() -> list[Segment]

Engine

Engine(overfetch: int = 2)

sync_status property

sync_status: dict[str, Any] | None

The background sync's last run: synced_at and error; None before it has run.

version property

version: int | None

publish

publish(
    updates: Mapping[str, Index | None],
    *,
    namespace: str = "default",
) -> None

sync

sync() -> int | None

Loads the database's latest version now; only for engines from Database.engine().

namespace

namespace(name: str) -> Namespace

The current version of namespace name; NamespaceNotFoundError if there is none.

namespaces

namespaces() -> list[str]

get

get(name: str) -> Index | None

names

names() -> list[str]

complete

complete(
    query: str,
    layers: Sequence[str],
    limit: int = 10,
    *,
    contexts: Sequence[str] | None = None,
    ignore_missing_layers: bool = False,
) -> list[Suggestion]

Namespace.complete in the default namespace.

complete_aliases

complete_aliases(
    query: str,
    layers: Sequence[str],
    limit: int = 10,
    *,
    contexts: Sequence[str] | None = None,
    ignore_missing_layers: bool = False,
) -> list[AliasSuggestion]

vector_search

vector_search(
    vector: Vector,
    layers: Sequence[str],
    limit: int = 10,
    *,
    contexts: Sequence[str] | None = None,
    ignore_missing_layers: bool = False,
) -> list[Suggestion]

hybrid_search

hybrid_search(
    text: str,
    vector: Vector,
    layers: Sequence[str],
    limit: int = 10,
    *,
    fusion: FusionKind = "rrf",
    rrf_k: float = 60.0,
    semantic_weight: float = 0.5,
    candidates: int | None = None,
    contexts: Sequence[str] | None = None,
    ignore_missing_layers: bool = False,
) -> list[HybridSuggestion]

Namespace

One version of one namespace; every search through it sees that version.

name property

name: str

version property

version: int

get

get(name: str) -> Index | None

names

names() -> list[str]

complete

complete(
    query: str,
    layers: Sequence[str],
    limit: int = 10,
    *,
    contexts: Sequence[str] | None = None,
    ignore_missing_layers: bool = False,
) -> list[Suggestion]

Later layers override earlier ones per document id; a missing layer raises LayerNotFoundError.

complete_aliases

complete_aliases(
    query: str,
    layers: Sequence[str],
    limit: int = 10,
    *,
    contexts: Sequence[str] | None = None,
    ignore_missing_layers: bool = False,
) -> list[AliasSuggestion]

vector_search

vector_search(
    vector: Vector,
    layers: Sequence[str],
    limit: int = 10,
    *,
    contexts: Sequence[str] | None = None,
    ignore_missing_layers: bool = False,
) -> list[Suggestion]

hybrid_search

hybrid_search(
    text: str,
    vector: Vector,
    layers: Sequence[str],
    limit: int = 10,
    *,
    fusion: FusionKind = "rrf",
    rrf_k: float = 60.0,
    semantic_weight: float = 0.5,
    candidates: int | None = None,
    contexts: Sequence[str] | None = None,
    ignore_missing_layers: bool = False,
) -> list[HybridSuggestion]

Replica

Replica(
    database: Database,
    engine: Engine,
    *,
    popularity_weight: float = 0.4,
    short_query_chars: int = 3,
    short_query_limit: int = 100,
    short_query_cache_entries: int = 10000,
    vector_threads: int = 1,
)

version property

version: int

sync

sync() -> int | None

Many writers

ChangeSet

ChangeSet()

namespace

namespace(name: str) -> NamespaceChanges

upsert

upsert(
    index: str,
    documents: Documents,
    vectors: Vectors | None = None,
) -> None

delete

delete(index: str, ids: Sequence[Id]) -> None

NamespaceChanges

The changes of a ChangeSet in one namespace.

name property

name: str

upsert

upsert(
    index: str,
    documents: Documents,
    vectors: Vectors | None = None,
) -> None

delete

delete(index: str, ids: Sequence[Id]) -> None

Ingestor

Ingestor(
    database: Database,
    owner: str,
    *,
    lease_ttl_seconds: float = 30.0,
    max_change_sets: int = 1000,
    compact: bool = True,
)

is_active property

is_active: bool

run_once

run_once() -> dict[str, Any]

release

release() -> None

Documents

Document

Document(
    id: Id,
    text: str,
    popularity: float = 0.0,
    *,
    synonyms: Sequence[str] = ...,
    abbreviations: Sequence[str] = ...,
    contexts: Sequence[str] = ...,
    vector: Vector | None = None,
)

id property

id: Id

text property

text: str

popularity property

popularity: float

synonyms property

synonyms: list[str]

abbreviations property

abbreviations: list[str]

contexts property

contexts: list[str]

to_dict

to_dict() -> DocumentDict

DocumentDict

Bases: TypedDict

id instance-attribute

id: Id

text instance-attribute

text: str

popularity instance-attribute

popularity: float

synonyms instance-attribute

synonyms: Sequence[str]

abbreviations instance-attribute

abbreviations: Sequence[str]

contexts instance-attribute

contexts: Sequence[str]

vector instance-attribute

vector: Vector

Id module-attribute

Id = int | str

A document id: an int, or a string key.

Documents module-attribute

Documents = Iterable[DocumentDict | Document] | Any

Dicts, Documents, or a pandas, polars or pyarrow table with those columns.

Vector module-attribute

Vector = Buffer | Sequence[float]

An embedding: a 1-D float32 array or a list of floats.

Vectors module-attribute

Vectors = Buffer | Sequence[Sequence[float]]

One embedding row per document: a float32 array of shape (n, dim), or lists.

key_id

key_id(key: str) -> int

Suggestions

Suggestion

id instance-attribute

id: Id

text instance-attribute

text: str

score instance-attribute

score: float

kind instance-attribute

kind: MatchKind

highlights instance-attribute

highlights: list[tuple[int, int]]

(start, end) character offsets of text that matched the query.

layer instance-attribute

layer: str | None

AliasSuggestion

id instance-attribute

id: Id

text instance-attribute

text: str

score instance-attribute

score: float

layer instance-attribute

layer: str | None

HybridSuggestion

id instance-attribute

id: Id

text instance-attribute

text: str

score instance-attribute

score: float

kind instance-attribute

kind: MatchKind

lexical_score instance-attribute

lexical_score: float | None

semantic_score instance-attribute

semantic_score: float | None

highlights instance-attribute

highlights: list[tuple[int, int]]

layer instance-attribute

layer: str | None

MatchKind

Bases: StrEnum

How a suggestion matched its query. Members compare equal to their string values.

EXACT class-attribute instance-attribute

EXACT = 'exact'

PREFIX class-attribute instance-attribute

PREFIX = 'prefix'

ABBREVIATION class-attribute instance-attribute

ABBREVIATION = 'abbreviation'

INFIX class-attribute instance-attribute

INFIX = 'infix'

FUZZY class-attribute instance-attribute

FUZZY = 'fuzzy'

SYNONYM class-attribute instance-attribute

SYNONYM = 'synonym'

SEMANTIC class-attribute instance-attribute

SEMANTIC = 'semantic'

FusionKind module-attribute

FusionKind = Literal['rrf', 'weighted', 'lexical_first']

asyncio

AsyncDatabase

AsyncDatabase(
    url: str,
    options: Mapping[str, str] | None = None,
    cache_dir: str | PathLike[str] | None = None,
    **build_options: Any,
)

Bases: _Lazy

A Database whose storage operations are awaitable: AsyncDatabase(url, ...) takes connect's arguments.

database property

database: Database

The synchronous Database, once opened.

namespace

namespace(name: str) -> AsyncDatabaseNamespace

Namespace name; storage opens on its first awaited call.

versions async

versions() -> list[int]

namespaces async

namespaces(version: int | None = None) -> list[str]

latest_version async

latest_version() -> int

index_names async

index_names(version: int | None = None) -> list[str]

manifest async

manifest(version: int | None = None) -> dict[str, Any]

begin async

begin(version: int | None = None) -> Transaction

commit async

commit(transaction: Transaction) -> dict[str, Any]

open_index async

open_index(
    name: str, version: int | None = None, **options: Any
) -> Index

engine async

engine(**options: Any) -> AsyncEngine

submit async

submit(changes: ChangeSet) -> str

pending_change_sets async

pending_change_sets() -> int

compact async

compact(index: str, **policy: Any) -> int | None

cleanup async

cleanup(**policy: Any) -> dict[str, int]

run_ingestor async

run_ingestor(ingestor: Ingestor) -> dict[str, Any]

One round of ingestor.run_once().

open async

open() -> AsyncDatabase

AsyncDatabaseNamespace

AsyncDatabaseNamespace(database: AsyncDatabase, name: str)

A DatabaseNamespace whose storage operations are awaitable.

name instance-attribute

name: str

index_names async

index_names(version: int | None = None) -> list[str]

begin async

begin(version: int | None = None) -> Transaction

open_index async

open_index(
    name: str, version: int | None = None, **options: Any
) -> Index

compact async

compact(index: str, **policy: Any) -> int | None

AsyncEngine

AsyncEngine(engine: Engine)

An Engine whose sync() is awaitable; completions stay synchronous.

sync async

sync() -> int | None

Errors

Every error derives from CompletypeError. NotFoundError is also a LookupError, InvalidInputError a ValueError, and StorageError an OSError. NamespaceNotFoundError and LayerNotFoundError are NotFoundErrors that carry the missing name and the names that exist in available.

CompletypeError

Bases: Exception

ConflictError

Bases: CompletypeError

CorruptionError

Bases: CompletypeError

NotFoundError

Bases: CompletypeError, LookupError

NamespaceNotFoundError

Bases: NotFoundError

name instance-attribute

name: str

available instance-attribute

available: list[str]

LayerNotFoundError

Bases: NotFoundError

name instance-attribute

name: str

namespace instance-attribute

namespace: str

version instance-attribute

version: int

available instance-attribute

available: list[str]

InvalidInputError

Bases: CompletypeError, ValueError

StorageError

Bases: CompletypeError, OSError

Collections

The collections layer.

Client

Client(
    url: str = "memory://",
    *,
    sync_every: float | None = 5.0,
    cache_dir: str | PathLike[str] | None = None,
    options: Mapping[str, str] | None = None,
    tags: Mapping[str, str] | None = None,
    min_word_chars: int = 3,
    max_edit_distance: int = 2,
    fuzzy_prefix_chars: int = 7,
    vector_bits: int = 4,
    compact_keys: bool = False,
    build_threads: int = 1,
)

database property

database: Database

namespace

namespace(name: str) -> ClientNamespace

collections

collections() -> list[str]

collection

collection(name: str) -> Collection

create_collection

create_collection(
    name: str,
    *,
    optimize: OptimizeKind = "auto",
    fanout: int = 4,
    max_segments: int = 16,
    max_hidden_fraction: float = 0.25,
    min_interval: float = 30.0,
) -> Collection

get_or_create_collection

get_or_create_collection(
    name: str,
    *,
    optimize: OptimizeKind = "auto",
    fanout: int = 4,
    max_segments: int = 16,
    max_hidden_fraction: float = 0.25,
    min_interval: float = 30.0,
) -> Collection

drop_collection

drop_collection(name: str) -> None

sync

sync() -> int | None

ClientNamespace

The collections of one namespace.

name property

name: str

collections

collections() -> list[str]

collection

collection(name: str) -> Collection

create_collection

create_collection(
    name: str,
    *,
    optimize: OptimizeKind = "auto",
    fanout: int = 4,
    max_segments: int = 16,
    max_hidden_fraction: float = 0.25,
    min_interval: float = 30.0,
) -> Collection

get_or_create_collection

get_or_create_collection(
    name: str,
    *,
    optimize: OptimizeKind = "auto",
    fanout: int = 4,
    max_segments: int = 16,
    max_hidden_fraction: float = 0.25,
    min_interval: float = 30.0,
) -> Collection

drop_collection

drop_collection(name: str) -> None

Collection

name property

name: str

namespace property

namespace: str

add

add(
    documents: Documents, vectors: Vectors | None = None
) -> int

Adds documents, replacing any with the same id; durable on return. Returns the new version.

delete

delete(ids: Sequence[Id]) -> int

complete

complete(
    query: str,
    limit: int = 10,
    *,
    aliases: bool = False,
    layers: Sequence[str] | None = None,
    contexts: Sequence[str] | None = None,
    vector: Vector | None = None,
    ignore_missing_layers: bool = False,
) -> list[Suggestion]

Completions, best first; Suggestion.layer is the collection each came from.

optimize

optimize() -> int | None

stats

stats() -> CollectionStats

CollectionStats

Bases: TypedDict

documents instance-attribute

documents: int

segments instance-attribute

segments: int

bytes instance-attribute

bytes: int

version instance-attribute

version: int

committed_at instance-attribute

committed_at: float

synced_version instance-attribute

synced_version: int

synced_at instance-attribute

synced_at: float | None

sync_error instance-attribute

sync_error: str | None

optimize_error instance-attribute

optimize_error: str | None

OptimizeKind module-attribute

OptimizeKind = Literal['auto', 'off']

AsyncClient

AsyncClient(url: str = 'memory://', **options: Any)

Bases: _Lazy

A Client whose storage calls are awaitable: AsyncClient(url, ...) takes Client's arguments.

client property

client: Client

The synchronous Client, once opened.

namespace

namespace(name: str) -> AsyncClientNamespace

The collections of namespace name; storage opens on its first awaited call.

collections async

collections() -> list[str]

collection async

collection(name: str) -> AsyncCollection

create_collection async

create_collection(
    name: str, **settings: Any
) -> AsyncCollection

get_or_create_collection async

get_or_create_collection(
    name: str, **settings: Any
) -> AsyncCollection

drop_collection async

drop_collection(name: str) -> None

sync async

sync() -> int | None

open async

open() -> AsyncClient

AsyncCollection

AsyncCollection(collection: Collection)

A Collection whose writes and storage calls are awaitable; complete stays synchronous.

name property

name: str

namespace property

namespace: str

add async

add(
    documents: Documents, vectors: Vectors | None = None
) -> int

delete async

delete(ids: Sequence[Id]) -> int

optimize async

optimize() -> int | None

stats async

stats() -> CollectionStats

complete

complete(
    query: str, limit: int = 10, **options: Any
) -> list[Suggestion]

AsyncClientNamespace

AsyncClientNamespace(client: AsyncClient, name: str)

A ClientNamespace whose storage calls are awaitable.

name instance-attribute

name: str

collections async

collections() -> list[str]

collection async

collection(name: str) -> AsyncCollection

create_collection async

create_collection(
    name: str, **settings: Any
) -> AsyncCollection

get_or_create_collection async

get_or_create_collection(
    name: str, **settings: Any
) -> AsyncCollection

drop_collection async

drop_collection(name: str) -> None