SessionIndex
A local, in-session index for real-time indexing and querying. All operations (add_docs, delete_docs, query) run entirely in-memory with no
cloud round trips (~1-10 ms). Open a session with
MossClient.session(), which auto-loads an
existing cloud index by name or starts empty. Call push_index() at the end of the
session to persist the index to the cloud for future retrieval, or
save_to_disk() to keep it on this device.
Properties
- name (
str): The index name. - doc_count (
int): Number of documents in the local session index. - model_id (
str): The embedding model the session uses, or"custom". A load moves the session to the loaded model, andadd_docsandqueryread it on every call. The value is as of the last completed call, so reading it never waits for a call in progress, and it still reads afterclose(). (moss 1.16.0+)
Methods
add_docs(docs, options)
Add or update documents in the local session index. Embeddings are generated locally
via the Rust core - no cloud round trip. When the session uses model_id="custom", each
document must have .embedding set.
docs takes the same inputs as
MossClient.create_index(): dicts, JSON
array or JSON Lines text, and .json, .jsonl, .ndjson, .txt, .md and .markdown file
paths, besides DocumentInfo objects. Text and markdown files are chunked natively. (moss 1.18.0+)
Parameters
- docs (
DocsInput) -DocumentInfoobjects, dicts, JSON array or JSON Lines text, orpathlib.Pathobjects for files. Astris always read as JSON text, never as a path. (moss 1.18.0+ for anything but a list ofDocumentInfo) - options (Optional[
MutationOptions] =None) - chunker (
Optional[Chunker]=None) - keyword-only. A synchronous function from a document’s text to a list of chunk strings. SeeChunker. (moss 1.18.0+) - chunking (Optional[
Chunking] =None) - keyword-only. Tunes the native chunker, and also chunksDocumentInfo, dict and JSON input. Passchunkerorchunking, not both. (moss 1.18.0+)
Returns
Tuple[int, int] - (added_count, updated_count)
Raises
InvalidArgumentError- for invalid JSON, an unsupported file type, a file with no text to index, or achunkerchunk of more than 2,000 characters. SeeChunking.TypeError- when bothchunkerandchunkingare passed.ValueError- whenchunkerorchunkingis passed to a session that usesmodel_id="custom", because chunks have no embeddings.
delete_docs(doc_ids)
Delete documents from the local session index by their IDs.
Parameters
- doc_ids (
List[str])
Returns
int - the number of documents deleted.
get_docs(options)
Retrieve documents from the local session index.
Parameters
- options (Optional[
GetDocumentsOptions] =None)
Returns
List[DocumentInfo]
query(query, options)
Perform a semantic search over the local session index. Runs entirely in-memory
(~1-10 ms) with no cloud call. Supports the same metadata filter syntax as
MossClient.query().
When the session uses model_id="custom", provide a query embedding via
QueryOptions.embedding.
Parameters
- query (
str) - options (Optional[
QueryOptions] =None)
Returns
SearchResult
push_index()
Push the local session index to the cloud. The cloud index is created, or replaced if
one already exists with the same name. For a built-in model the service re-embeds the
text with that model, so the index loads and answers text queries like one built with
create_index. A custom-model session keeps its own embeddings.
Returns
PushIndexResult
save_to_disk(cache_path)
Save the session under <cache_path>/<name>/, so a later session with the same name can
restore it with load_from_disk(). Open that
session with auto_load_on_init=False so the restore downloads no index. A failed or
interrupted save leaves the last saved snapshot loadable. For a built-in model the snapshot
records the model id and the exact model artifact, so the restored session embeds text with
the same model. (moss 1.16.0+)
Parameters
- cache_path (
str): Directory that holds one snapshot directory per session name. A relative path resolves against the current working directory, and~is not expanded.
Returns
None
load_from_disk(cache_path, rebuild_legacy)
Restore a session saved by save_to_disk() from
<cache_path>/<name>/. The snapshot replaces this session’s documents and model, so after a
custom-model snapshot loads, add_docs and query need embeddings. If the session has
already loaded the snapshot’s model, it keeps that model instead of loading it again. A missing or damaged snapshot raises
MossError with code DESERIALIZATION and leaves the session as
it was before the call. (moss 1.16.0+)
A snapshot that an older core saved for a built-in model has no model artifact identity, so
it can only load as a custom-model session. With rebuild_legacy=True (the default), a
session opened with that same built-in model rebuilds the snapshot instead: the call
re-embeds the stored documents with the current model and saves the snapshot back, so later
loads skip the rebuild. The rebuild needs the model, so the cloud must be
reachable. When the model cannot be loaded, the call raises MossError with code
MODEL_UNAVAILABLE and changes neither the snapshot nor the session, so retry later instead
of discarding the snapshot. Custom-model sessions and snapshots of another model load
without a rebuild. Pass rebuild_legacy=False to load such a snapshot as a custom-model
session.
Parameters
- cache_path (
str): Directory passed tosave_to_disk, resolved the same way. - rebuild_legacy (
bool=True): Keyword-only. Rebuild a built-in model snapshot that has no model artifact identity.
Returns
int - the number of documents loaded.
close()
Send the final usage report, then free the session’s native memory. Waits until the
report arrives or 2 seconds pass. Safe to call more than once. Afterwards name and
model_id still read and every other member raises InvalidArgumentError.
MossClient.close() also closes every session the client opened.
(moss 1.15.0+)
SessionIndex is also a context manager: leaving an async with or with block calls
close() automatically.