Skip to main content
Elixir SDK / Moss.Client

​
Moss.Client

The single entry point for the Moss Elixir SDK. Construct a client with your project credentials, then use it for cloud index CRUD, loading indexes into memory, local querying, and opening Moss.Session handles for real-time indexing. Cloud operations (create_index, add_docs, delete_docs, get_docs, get_index, list_indexes, delete_index, get_job_status) read and write the server-side index. Local operations (load_index, unload_index, has_index, query, refresh_index, get_index_info) act on indexes loaded into memory. An index must be loaded with load_index/3 before you can query/4 it. Once loaded, queries run entirely in-memory with no network round trip.

​
Methods

​
new(project_id, project_key, opts)

Create a new client. Starts an internal local index manager and generates a per-client UUID for telemetry correlation. The index API URL is resolved from the MOSS_INDEX_URL environment variable, falling back to the default cloud endpoint.

​
Parameters

  • project_id (String.t())
  • project_key (String.t())
  • opts (keyword() = [])

​
Returns

{:ok, Moss.Client.t()} or {:error, String.t()} 
{:ok, client} = Moss.Client.new("your-project-id", "your-project-key")

​
create_index(client, name, docs, model_id)

Create a new cloud index and populate it with documents. model_id is optional and defaults to "moss-minilm". Pass "moss-mediumlm" for higher accuracy, or "custom" when every document carries a pre-computed embedding.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())
  • docs (list of Moss.DocumentInfo)
  • model_id (String.t() = "moss-minilm")

​
Returns

{:ok, Moss.MutationResult.t()} or {:error, String.t()} 
{:ok, result} = Moss.Client.create_index(client, "faqs", documents)
{:ok, result} = Moss.Client.create_index(client, "faqs", documents, "moss-mediumlm")

​
add_docs(client, name, docs, opts)

Add or update documents in an existing cloud index.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())
  • docs (list of Moss.DocumentInfo)
  • opts (keyword() = []): supports :upsert (boolean). When omitted, the server default applies.

​
Returns

{:ok, Moss.MutationResult.t()} or {:error, String.t()} 
{:ok, result} = Moss.Client.add_docs(client, "faqs", more_docs, upsert: true)

​
delete_docs(client, name, doc_ids)

Delete documents from a cloud index by their IDs.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())
  • doc_ids (list of String.t())

​
Returns

{:ok, Moss.MutationResult.t()} or {:error, String.t()} 
{:ok, result} = Moss.Client.delete_docs(client, "faqs", ["doc1", "doc2"])

​
get_docs(client, name, opts)

Retrieve documents from a cloud index.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())
  • opts (keyword() = []): supports :doc_ids (list of strings). When provided, only those documents are fetched; otherwise all documents are returned.

​
Returns

{:ok, [Moss.DocumentInfo.t()]} or {:error, String.t()} 
{:ok, docs} = Moss.Client.get_docs(client, "faqs", doc_ids: ["doc1"])

​
get_index(client, name)

Get metadata for a cloud index.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())

​
Returns

{:ok, Moss.IndexInfo.t()} or {:error, String.t()}

​
list_indexes(client)

List all cloud indexes for the project, with their metadata.

​
Parameters

  • client (Moss.Client.t())

​
Returns

{:ok, [Moss.IndexInfo.t()]} or {:error, String.t()}

​
delete_index(client, name)

Delete a cloud index and all of its data.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())

​
Returns

{:ok, boolean()} or {:error, String.t()}

​
get_job_status(client, job_id)

Poll the status of an asynchronous job, such as the one returned by create_index/4 or add_docs/4.

​
Parameters

  • client (Moss.Client.t())
  • job_id (String.t())

​
Returns

{:ok, Moss.JobStatusResponse.t()} or {:error, String.t()} 
{:ok, status} = Moss.Client.get_job_status(client, result.job_id)

​
load_index(client, name, opts)

Download a cloud index into memory for fast local querying. An index must be loaded before you can query/4 it; once loaded, queries run entirely in-memory with no network round trip. Set auto_refresh: true to keep the loaded index in sync with cloud updates by polling every :polling_interval seconds.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())
  • opts (keyword() = []): supports :auto_refresh (boolean, default false) and :polling_interval (integer seconds, default 600).

​
Returns

{:ok, Moss.IndexInfo.t()} or {:error, String.t()} 
{:ok, info} = Moss.Client.load_index(client, "faqs")
{:ok, info} = Moss.Client.load_index(client, "faqs", auto_refresh: true, polling_interval: 300)

​
query(client, name, query_text, opts)

Perform a semantic similarity search against a loaded index. Call load_index/3 first; queries then run entirely in-memory. Metadata filtering is supported on locally loaded indexes. For built-in models the query is embedded automatically. For indexes created with model_id: "custom", pass the query embedding via the :embedding option.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())
  • query_text (String.t())
  • opts (keyword() = []): supports :top_k (integer, default 5), :alpha (float, default 0.8), :filter (map), and :embedding (list of floats, required for model_id: "custom").

​
Returns

{:ok, Moss.SearchResult.t()} or {:error, String.t()} 
{:ok, result} = Moss.Client.query(client, "faqs", "return a damaged product", top_k: 3, alpha: 0.6)

# With a metadata filter
{:ok, result} = Moss.Client.query(client, "faqs", "running shoes",
  top_k: 5,
  filter: %{
    "$and" => [
      %{"field" => "category", "condition" => %{"$eq" => "shoes"}},
      %{"field" => "price", "condition" => %{"$lt" => "100"}}
    ]
  }
)
alpha tunes the hybrid blend: 1.0 is pure semantic, 0.0 is pure keyword, and the default 0.8 is semantic-heavy. Filter operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $near. Logical combinators: $and, $or (nestable).

​
refresh_index(client, name)

Force an immediate refresh of a loaded index from the cloud, picking up any server-side changes since it was loaded.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())

​
Returns

{:ok, Moss.RefreshResult.t()} or {:error, String.t()}

​
get_index_info(client, name)

Get metadata for an index that is currently loaded into memory.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())

​
Returns

{:ok, Moss.IndexInfo.t()} or {:error, String.t()}

​
has_index(client, name)

Check whether an index is currently loaded into memory.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())

​
Returns

boolean()

​
unload_index(client, name)

Unload an index from memory, freeing its resources. The cloud copy is unaffected.

​
Parameters

  • client (Moss.Client.t())
  • name (String.t())

​
Returns

{:ok, :ok} or {:error, String.t()}

​
session(client, index_name, opts)

Create or resume a local, real-time Moss.Session. If a cloud index with index_name already exists, it is silently loaded into the session; otherwise the session starts empty. Built-in models are pre-warmed to eliminate cold-start delay on the first query. index_name is also the target when Moss.Session.push_index/1 is later called.

​
Parameters

  • client (Moss.Client.t())
  • index_name (String.t())
  • opts (keyword() = []): supports :model_id (String.t(), default "moss-minilm"; other options "moss-mediumlm", "custom") and :server_name (GenServer name for the session process).

​
Returns

{:ok, GenServer.server()} or {:error, String.t()} 
{:ok, session} = Moss.Client.session(client, "session-abc")
{:ok, custom} = Moss.Client.session(client, "custom-session", model_id: "custom")