Skip to main content
moss v1.4.0 moss / MossClient

​
MossClient

Semantic search client for vector similarity operations. All mutations and reads go through the Rust core. Querying runs against an index that has been loaded into memory with load_index() (or load_indexes()) - load the index before you query it. For real-time, local-first indexing during a live interaction, use session(), which returns a SessionIndex.

​
Methods

​
create_index(name, docs, model_id, wait)

Create a new index and populate it with documents. When model_id is omitted, the SDK picks "moss-minilm" when no documents carry pre-computed embeddings and "custom" when every document provides an embedding. Mixed documents are rejected. By default (wait=True) the call blocks until the build finishes and returns a MutationResult. With wait=False it submits the build and returns a JobHandle as soon as the upload is accepted, so you can fire the build, tear down the machine, and check on it later.
The wait parameter and JobHandle require moss 1.7.1+ (which pulls inferedge-moss-core 0.20.1).

​
Parameters

  • name (str)
  • docs (List[DocumentInfo])
  • model_id (Optional[str] = None)
  • wait (bool = True) — when False, return a JobHandle immediately instead of blocking until the build completes.

​
Returns

MutationResult when wait=True, otherwise JobHandle.

​
Example: submit without waiting

# Submit the build and return right away
job = await client.create_index("my-index", docs, "moss-minilm", wait=False)
print(job.job_id)                 # available immediately

# Optional: watch progress
status = await job.status()       # status, progress, current_phase

# Block until done if you want the result in-process
result = await job.wait()

# Or reconnect later from a fresh client and poll by id
status = await client.get_job_status(job.job_id)

​
add_docs(name, docs, options)

Add or update documents in an index.

​
Parameters

​
Returns

MutationResult

​
delete_docs(name, doc_ids)

Delete documents from an index by their IDs.

​
Parameters

  • name (str)
  • doc_ids (List[str])

​
Returns

MutationResult

​
get_job_status(job_id)

Get the status of a bulk operation job.

​
Parameters

  • job_id (str)

​
Returns

JobStatusResponse

​
get_index(name)

Get information about a specific index.

​
Parameters

  • name (str)

​
Returns

IndexInfo

​
list_indexes()

List all indexes with their information.

​
Returns

List[IndexInfo]

​
delete_index(name)

Delete an index and all its data.

​
Parameters

  • name (str)

​
Returns

bool

​
get_docs(name, options)

Retrieve documents from an index.

​
Parameters

​
Returns

List[DocumentInfo]

​
load_index(name, auto_refresh, polling_interval_in_seconds)

Downloads an index from the cloud into memory for fast local querying. An index must be loaded before you can query() it; once loaded, queries run entirely in-memory (~1-10 ms). Set auto_refresh=True to keep the loaded index in sync with cloud updates by polling every polling_interval_in_seconds.

​
Parameters

  • name (str)
  • auto_refresh (bool = False)
  • polling_interval_in_seconds (int = 600)

​
Returns

str

​
unload_index(name)

Unload an index from memory.

​
Parameters

  • name (str)

​
query(name, query, options)

Perform a semantic similarity search against a loaded index. Call load_index(name) first; queries then run entirely in-memory (~1-10 ms). Metadata filtering is supported on locally loaded indexes.

​
Parameters

  • name (str)
  • query (str)
  • options (Optional[QueryOptions] = None): Query options (top_k, alpha, embedding, filter).

​
Returns

SearchResult

​
query_multi_index(names, query, options)

Search across multiple loaded indexes and return the global top-K. All requested indexes must be loaded locally and share the same embedding model. Each result document is tagged with its source index_name. options.top_k is the global cap across the merged result. See Multi-index search.

​
Parameters

  • names (List[str]): Non-empty list of loaded index names.
  • query (str)
  • options (Optional[QueryOptions] = None)

​
Returns

SearchResult - docs carry index_name per result.

​
load_indexes(names, auto_refresh, polling_interval_in_seconds)

Bulk-load many indexes into memory. Best-effort: a failure on one name does not roll back the others. auto_refresh and polling_interval_in_seconds apply to the whole batch.

​
Parameters

  • names (List[str])
  • auto_refresh (bool = False)
  • polling_interval_in_seconds (int = 600)

​
Returns

LoadIndexesResult

​
unload_indexes(names)

Bulk-unload many indexes from memory. Idempotent for names that aren’t loaded.

​
Parameters

  • names (List[str])

​
session(index_name, model_id)

Create or resume a local, real-time SessionIndex. If a cloud index with the given name already exists, it is auto-loaded into the session (no re-embedding); otherwise the session starts empty. The index_name is also the target when push_index() is later called. Raises ValueError if an existing cloud index uses a different model than an explicit model_id. See the Sessions guide.

​
Parameters

  • index_name (str)
  • model_id (Optional[str] = None): Local embedding model. Defaults to "moss-minilm". Other options: "moss-mediumlm", "custom".

​
Returns

SessionIndex