> ## Documentation Index > Fetch the complete documentation index at: https://docs.moss.dev/llms.txt > Use this file to discover all available pages before exploring further. # Types > Structs and enums used across the Moss Swift SDK. [Swift SDK](./api) / Types Reference for the structs and enums passed to and returned from [`MossClient`](./classes/MossClient) and [`MossSession`](./classes/MossSession). ## DocumentInfo A document stored in or returned from an index. Conforms to `Codable`. ```swift theme={null} public struct DocumentInfo: Codable { public let id: String public let text: String public let metadata: [String: String]? // optional, defaults to nil public let embedding: [Float]? // optional, defaults to nil public let payload: String? // optional, verbatim — defaults to nil } ``` | Field | Type | Description | | ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `String` | Unique document id. | | `text` | `String` | Document text (embedded and searched). | | `metadata` | `[String: String]?` | Optional string key/value metadata, usable in filters. | | `embedding` | `[Float]?` | Optional pre-computed embedding. Required when the session/index uses the `"custom"` model. | | `payload` | `String?` | Optional opaque structured payload, stored and returned verbatim — never embedded or searched. See [Exact / Graph Retrieval](../swift/graph-retrieval#verbatim-structured-payload). | Store an `Encodable` value as the payload with the `structured:` initializer, and read it back typed with `decodedPayload(_:)`: ```swift theme={null} public init(id: String, text: String, metadata: [String: String]? = nil, embedding: [Float]? = nil, structured: P) throws public func decodedPayload(_ type: P.Type) throws -> P? ``` ## QueryOptions ```swift theme={null} public struct QueryOptions { public var topK: Int // default 5 public var alpha: Float // default 0.8 public var filter: Filter? public var filterJson: String? public var groupByParent: ParentGrouping? } ``` | Field | Type | Description | | --------------- | ------------------------------------ | ------------------------------------------------------------------------------------------ | | `topK` | `Int` | Number of results to return. Default `5`. | | `alpha` | `Float` | Hybrid blend: `1.0` = pure semantic, `0.0` = pure keyword. Default `0.8` (semantic-heavy). | | `filter` | [`Filter?`](#filter) | Typed metadata filter (preferred). Takes precedence over `filterJson` when both are set. | | `filterJson` | `String?` | Legacy metadata filter as a JSON string (`$eq`, `$and`, `$in`, `$near`, …). | | `groupByParent` | [`ParentGrouping?`](#parentgrouping) | Collapse sibling hits sharing a parent id into one result per unit. | See [Querying](./querying) for hybrid-search examples and [Exact / Graph Retrieval](./graph-retrieval) for the typed `Filter` DSL and parent grouping. ## SearchResult Returned by `query(...)`. ```swift theme={null} public struct SearchResult { public let docs: [QueryResult] public let query: String public let timeMs: UInt64 } ``` ## QueryResult A single match within a [`SearchResult`](#searchresult). ```swift theme={null} public struct QueryResult { public let id: String public let score: Float public let text: String public let metadata: [String: String]? public let payload: String? } ``` `payload` is the document's verbatim structured payload (`nil` when it has none); read it typed with `decodedPayload(_:)` — see [Verbatim structured payload](./graph-retrieval#verbatim-structured-payload). ## Filter A composable, typed metadata predicate used by [`getDocs(where:)`](./classes/MossSession#getdocs_where_sortby_ascending) and [`QueryOptions.filter`](#queryoptions). Serialized internally to the engine's filter format — no JSON to hand-write. See [the Filter DSL](./graph-retrieval#the-filter-dsl) for examples. ```swift theme={null} public indirect enum Filter { case equals(String, FilterValue) case notEquals(String, FilterValue) case greaterThan(String, FilterValue) case greaterThanOrEqual(String, FilterValue) case lessThan(String, FilterValue) case lessThanOrEqual(String, FilterValue) case isIn(String, [FilterValue]) case notIn(String, [FilterValue]) case near(field: String, lat: Double, lng: Double, withinMeters: Double) case and([Filter]) case or([Filter]) case raw(String) // escape hatch: raw engine-format JSON } ``` Numeric comparisons (`greaterThan`, `lessThanOrEqual`, …) are numeric-aware even though metadata is stored as strings (`"9" < "50"`). `.raw` with invalid JSON throws rather than silently matching everything. ## FilterValue A typed metadata value used inside a [`Filter`](#filter). Literal-expressible, so you can write `"shoes"`, `27`, `0.7`, or `false` directly wherever a `FilterValue` is expected. ```swift theme={null} public enum FilterValue { case string(String) case int(Int) case double(Double) case bool(Bool) } ``` ## ParentGrouping Collapses sibling documents that share a parent id into one result per unit, assembling sibling text in `orderField` order (numeric-aware). Passed to [`GetDocsOptions.groupByParent`](#getdocsoptions) and [`QueryOptions.groupByParent`](#queryoptions). ```swift theme={null} public struct ParentGrouping { public var parentField: String // e.g. "article_id" public var orderField: String // e.g. "chunk_index" } ``` ## GetDocsOptions Full-control input to [`getDocs(options:)`](./classes/MossSession#getdocs_options). Combine an id list, a metadata filter, sorting, and parent grouping in one deterministic fetch. ```swift theme={null} public struct GetDocsOptions { public var ids: [String]? // exact ids, returned in this order public var filter: Filter? // metadata predicate public var sortBy: String? // metadata field to order by (numeric-aware) public var ascending: Bool // default true public var groupByParent: ParentGrouping? } ``` See [Exact / Graph Retrieval](./graph-retrieval) for worked examples. ## ModelRef Reference to an embedding model with version information. Surfaced on [`IndexInfo`](#indexinfo). ```swift theme={null} public struct ModelRef { public let id: String public let version: String? } ``` | Field | Type | Description | | --------- | --------- | ------------------------------------------- | | `id` | `String` | Model identifier. | | `version` | `String?` | Model version (semver or build identifier). | ## IndexInfo Metadata about a cloud index. Returned by [`getIndex`](./classes/MossClient#getindex_) and [`listIndexes`](./classes/MossClient#listindexes). ```swift theme={null} public struct IndexInfo { public let id: String public let name: String public let status: String public let docCount: Int public let model: ModelRef public let version: String? public let createdAt: String? public let updatedAt: String? } ``` | Field | Type | Description | | ----------- | ---------- | ------------------------------------------------------------------------ | | `id` | `String` | Unique identifier of the index. | | `name` | `String` | Human-readable name of the index. | | `status` | `String` | Current build status (e.g. `NotStarted`, `Building`, `Ready`, `Failed`). | | `docCount` | `Int` | Number of documents in the index. | | `model` | `ModelRef` | Embedding model bound to the index. | | `version` | `String?` | Index build/format version. | | `createdAt` | `String?` | When the index was created. | | `updatedAt` | `String?` | When the index was last updated. | ## SessionOptions Passed to [`MossClient.session(_:options:)`](./classes/MossClient#session_options). ```swift theme={null} public struct SessionOptions { public var modelId: String? // optional, defaults to nil public var vectorQuantization: VectorQuantization = .default public var autoLoadOnInit: Bool = true } ``` | Field | Type | Description | | -------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `modelId` | `String?` | Embedding model id. `nil` = platform default (`moss-litelm` on iOS). Pass `"custom"` to supply embeddings via `DocumentInfo.embedding`. | | `vectorQuantization` | [`VectorQuantization`](#vectorquantization) | On-disk vector precision used when persisting with `MossSession.save(toCachePath:)`. Defaults to `.default` (platform-appropriate). | | `autoLoadOnInit` | `Bool` | When `true` (the default), `session(_:options:)` auto-loads the named index from the cloud at creation. Set `false` for a local-only, disk-first session: creation returns immediately and you load it yourself (restore from disk, hitting the cloud only on a miss). | With `autoLoadOnInit: false` the session starts empty until you load it. Calling `pushIndex()` on a session you never loaded overwrites the cloud index with the near-empty local one — use it for read-only or load-then-mutate flows. ## VectorQuantization On-disk vector precision for [`SessionOptions`](#sessionoptions), applied when a session is persisted with `MossSession.save(toCachePath:)`. ```swift theme={null} public enum VectorQuantization: UInt8 { case `default` = 0 // platform-appropriate (INT8 on iOS) case fp32 = 1 // full 32-bit precision case int8 = 2 // 8-bit scalar quantization (smaller on disk) } ``` ## PushIndexResult Returned by [`MossSession.pushIndex()`](./classes/MossSession#pushindex). Poll `jobId` with [`getJobStatus`](./classes/MossClient#getjobstatus_) until `status` is `ready`. ```swift theme={null} public struct PushIndexResult { public let jobId: String public let indexName: String public let docCount: Int public let status: String } ``` ## MutationResult Returned by the cloud document operations [`createIndex`](./classes/MossClient#createindex_docs_modelid), [`addDocs`](./classes/MossClient#adddocs_docs_upsert), and [`deleteDocs`](./classes/MossClient#deletedocs_docids) after the operation completes. ```swift theme={null} public struct MutationResult { public let jobId: String public let indexName: String public let docCount: Int } ``` | Field | Type | Description | | ----------- | -------- | -------------------------------------------------------- | | `jobId` | `String` | Identifier of the async job that performed the mutation. | | `indexName` | `String` | Name of the index that was mutated. | | `docCount` | `Int` | Number of documents in the index after the mutation. | ## RefreshResult Returned by [`refreshIndex`](./classes/MossClient#refreshindex_). ```swift theme={null} public struct RefreshResult { public let indexName: String public let previousUpdatedAt: String public let newUpdatedAt: String public let wasUpdated: Bool } ``` | Field | Type | Description | | ------------------- | -------- | ---------------------------------------------- | | `indexName` | `String` | Name of the index that was refreshed. | | `previousUpdatedAt` | `String` | Timestamp before the refresh. | | `newUpdatedAt` | `String` | Timestamp after the refresh. | | `wasUpdated` | `Bool` | `true` when a newer cloud version was applied. | ## JobStatus Returned by [`getJobStatus`](./classes/MossClient#getjobstatus_). ```swift theme={null} public struct JobStatus { public let jobId: String public let status: String public let progress: Double public let currentPhase: String? public let error: String? public let createdAt: String public let updatedAt: String public let completedAt: String? } ``` ## MemoryPressureLevel Passed to [`onMemoryPressure`](./classes/MossClient#onmemorypressure_). ```swift theme={null} public enum MemoryPressureLevel: UInt8 { case low = 0 // hint: drop hot caches case critical = 1 // drop everything reclaimable; on-disk caches kept } ``` ## MossError Thrown for any failure reported by the underlying runtime. Conforms to `LocalizedError`, so `error.localizedDescription` returns the message. ```swift theme={null} public struct MossError: LocalizedError { public let code: Int32 public let message: String } ```