Swift SDK / MossClient

MossClient

The entry point for the Swift SDK. Construct it with your project credentials (or a custom Authenticator), then open on-device sessions and track push jobs. All methods are async throws and dispatch native work onto a background thread. The underlying native client is thread-safe.

Example

import Moss

let client = try MossClient(projectId: "your-project-id", projectKey: "your-project-key")
defer { client.close() }

// Open an on-device session and search locally.
let session = try await client.session("docs")
try await session.addDocs([
  .init(id: "1", text: "Machine learning fundamentals"),
  .init(id: "2", text: "Deep learning neural networks"),
])
let results = try await session.query("AI and neural networks")

Constructors

init(projectId:projectKey:)

init(projectId: String, projectKey: String) throws

Creates a client backed by a static project key.

Parameter	Type	Description
`projectId`	`String`	Your project identifier.
`projectKey`	`String`	Your project authentication key. Prefer the `Authenticator` form for shipped apps so the key never ships in the binary.

init(projectId:authenticator:baseUrl:)

init(projectId: String, authenticator: any Authenticator, baseUrl: String? = nil) throws

Creates a client whose bearer tokens come from a custom Authenticator. Use this in shipped apps so the long-lived project key stays on your backend.

Parameter	Type	Description
`projectId`	`String`	Your project identifier.
`authenticator`	`any Authenticator`	Supplies a short-lived bearer token from your backend.
`baseUrl`	`String?`	Optional override for the API base URL.

Statics

sdkVersion

static var sdkVersion: String

The native runtime version string.

setModelCacheDir(_:)

static func setModelCacheDir(_ path: String) throws

Override where embedding-model files are cached. You normally don’t need this - the client caches under <Library/Caches>/moss-models/ automatically on first init. Call it before constructing your first client if you need a custom location (e.g. a shared App Group container).

Methods

close()

func close()

Frees the underlying native handle. Idempotent and safe to call while operations are in flight (it blocks until they drain). Also called automatically on deinit.

session(_:options:)

func session(_ name: String, options: SessionOptions = SessionOptions()) async throws -> MossSession
func session(_ name: String, modelId: String?) async throws -> MossSession

Opens an on-device MossSession. Documents are embedded locally with the bundled model (default moss-litelm on iOS) and queried without a network round-trip. Configure with SessionOptions — including autoLoadOnInit to skip the creation-time cloud load for a local-first startup.

let session = try await client.session("notes")
defer { session.close() }

By default the session auto-loads the named cloud index at creation. For a local-only, disk-first session, pass autoLoadOnInit: false so creation returns immediately and you control loading (restore from disk, hitting the cloud only on a miss):

let cachePath = NSSearchPathForDirectoriesInDomains(
    .cachesDirectory, .userDomainMask, true)[0]

let session = try await client.session(
    "notes", options: SessionOptions(autoLoadOnInit: false))

if try await session.loadFromDisk(cachePath: cachePath) == 0 {
    // Cache miss: pull from the cloud, then persist for next launch.
    _ = try await session.loadIndex("notes")
    try await session.save(toCachePath: cachePath)
}

createIndex(_:docs:modelId:)

func createIndex(_ name: String, docs: [DocumentInfo], modelId: String? = nil) async throws -> MutationResult

Creates a cloud index from the given documents and polls until it is ready. When modelId is nil the server picks a default ("custom" when documents carry pre-computed embeddings). Returns a MutationResult.

Parameter	Type	Description
`name`	`String`	Name of the index to create.
`docs`	`[DocumentInfo]`	Documents to index, optionally with pre-computed embeddings.
`modelId`	`String?`	Embedding model id. `nil` selects the server default.

let result = try await client.createIndex("docs", docs: [
  .init(id: "1", text: "Machine learning fundamentals"),
  .init(id: "2", text: "Deep learning neural networks"),
])

getIndex(_:)

func getIndex(_ name: String) async throws -> IndexInfo

Gets metadata about a single cloud index. Returns an IndexInfo. Throws if the index does not exist.

listIndexes()

func listIndexes() async throws -> [IndexInfo]

Lists all cloud indexes for the project. Returns an array of IndexInfo.

for index in try await client.listIndexes() {
  print("\(index.name): \(index.docCount) docs")
}

refreshIndex(_:)

func refreshIndex(_ name: String) async throws -> RefreshResult

Checks the cloud for a newer version of a loaded index and updates it in place if one exists. Returns a RefreshResult describing whether an update was applied.

loadIndex(_:options:)

func loadIndex(_ name: String, options: LoadIndexOptions = LoadIndexOptions()) async throws

Downloads a cloud index and loads it for fast local querying. Configure caching and background auto-refresh with LoadIndexOptions. Throws if the index does not exist or loading fails.

Parameter	Type	Description
`name`	`String`	Name of the index to load.
`options`	`LoadIndexOptions`	Cache path and auto-refresh configuration.

try await client.loadIndex("docs", options: .init(cachePath: cachePath))

query(::options:)

func query(_ indexName: String, _ query: String, options: QueryOptions = QueryOptions()) async throws -> SearchResult

Runs a semantic search against a loaded index. The index must be loaded with loadIndex(_:options:) first; querying an index that has not been loaded throws. Configure with QueryOptions and read matches from the returned SearchResult.

Parameter	Type	Description
`indexName`	`String`	Name of the loaded index to search.
`query`	`String`	Search query text.
`options`	`QueryOptions`	`topK`, `alpha`, and metadata filter.

try await client.loadIndex("docs", options: .init(cachePath: cachePath))
let results = try await client.query("docs", "vector search on mobile")
for doc in results.docs {
  print("\(doc.id): \(doc.score)")
}

unloadIndex(_:)

func unloadIndex(_ name: String) async throws

Unloads a previously loaded index, releasing the resources it held. Subsequent query(_:_:options:) calls for that index throw until it is loaded again.

addDocs(_:docs:upsert:)

func addDocs(_ name: String, docs: [DocumentInfo], upsert: Bool = true) async throws -> MutationResult

Adds or updates documents in a cloud index and polls until the rebuild completes. Returns a MutationResult.

Parameter	Type	Description
`name`	`String`	Name of the target index.
`docs`	`[DocumentInfo]`	Documents to add or update.
`upsert`	`Bool`	Update documents that already share an id. Default `true`.

getDocs(_:docIds:)

func getDocs(_ name: String, docIds: [String]? = nil) async throws -> [DocumentInfo]

Retrieves documents from a cloud index. Pass docIds to fetch specific documents; omit it to fetch all of them. Returns an array of DocumentInfo.

let all = try await client.getDocs("docs")
let some = try await client.getDocs("docs", docIds: ["1", "2"])

deleteDocs(_:docIds:)

func deleteDocs(_ name: String, docIds: [String]) async throws -> MutationResult

Deletes documents from a cloud index by id and polls until the rebuild completes. Returns a MutationResult.

Parameter	Type	Description
`name`	`String`	Name of the target index.
`docIds`	`[String]`	Ids of the documents to delete.

getJobStatus(_:)

func getJobStatus(_ jobId: String) async throws -> JobStatus

Gets the current status of an async job - for example, the job returned by MossSession.pushIndex. Poll until status is ready. Returns a JobStatus.

let push = try await session.pushIndex()
while try await client.getJobStatus(push.jobId).status != "ready" {
  try await Task.sleep(nanoseconds: 1_000_000_000)
}

deleteIndex(_:)

func deleteIndex(_ name: String) async throws -> Bool

Deletes a cloud index (e.g. one created by MossSession.pushIndex) and all its data. Returns true if deleted.

onMemoryPressure(_:)

func onMemoryPressure(_ level: MemoryPressureLevel = .critical) async throws -> Int

Frees reclaimable native memory in response to an OS memory-pressure signal. Wire this from UIApplication.didReceiveMemoryWarningNotification. Returns the number of indexes freed. See MemoryPressureLevel.

Python

JavaScript

Swift (iOS)

Elixir

Browser

C

MossClient

MossClient

Example

Constructors

init(projectId:projectKey:)

init(projectId:authenticator:baseUrl:)

Statics

sdkVersion

setModelCacheDir(_:)

Methods

close()

session(_:options:)

createIndex(_:docs:modelId:)

getIndex(_:)

listIndexes()

refreshIndex(_:)

loadIndex(_:options:)

query(::options:)

unloadIndex(_:)

addDocs(_:docs:upsert:)

getDocs(_:docIds:)

deleteDocs(_:docIds:)

getJobStatus(_:)

deleteIndex(_:)

onMemoryPressure(_:)

​MossClient

​Example

​Constructors

​init(projectId:projectKey:)

​init(projectId:authenticator:baseUrl:)

​Statics

​sdkVersion

​setModelCacheDir(_:)

​Methods

​close()

​session(_:options:)

​createIndex(_:docs:modelId:)

​getIndex(_:)

​listIndexes()

​refreshIndex(_:)

​loadIndex(_:options:)

​query(::options:)

​unloadIndex(_:)

​addDocs(_:docs:upsert:)

​getDocs(_:docIds:)

​deleteDocs(_:docIds:)

​getJobStatus(_:)

​deleteIndex(_:)

​onMemoryPressure(_:)

MossClient

Example

Constructors

init(projectId:projectKey:)

init(projectId:authenticator:baseUrl:)

Statics

sdkVersion

setModelCacheDir(_:)

Methods

close()

session(_:options:)

createIndex(_:docs:modelId:)

getIndex(_:)

listIndexes()

refreshIndex(_:)

loadIndex(_:options:)

query(::options:)

unloadIndex(_:)

addDocs(_:docs:upsert:)

getDocs(_:docIds:)

deleteDocs(_:docIds:)

getJobStatus(_:)

deleteIndex(_:)

onMemoryPressure(_:)