StorageEngine

public actor StorageEngine

The StorageEngine actor is responsible for managing the core storage functionality of the database. It handles the configuration, partitioning, and management of collections, shards, and indexes.

Properties:

  • baseURL: The base URL where the storage engine operates.
  • compressionMethod: The method used for compressing stored data.
  • fileProtectionType: The type of file protection applied to stored data.
  • collectionPartitionKeys: A dictionary mapping collection names to their partition keys.
  • activeShardManagers: A dictionary of active shard managers, keyed by collection name.
  • indexManagers: A dictionary of index managers, keyed by collection name.
  • statsEngine: A lazily initialized instance of StatsEngine for gathering storage statistics.

  • Undocumented

    Declaration

    Swift

    public var collectionPartitionKeys: [String : String]

  • Undocumented

    Declaration

    Swift

    public var activeShardManagers: [String : ShardManager]

  • Undocumented

    Declaration

    Swift

    public var indexManagers: [String : IndexManager<String>]

  • An enumeration representing errors that can occur in the storage engine.

    This enum conforms to the Error protocol, allowing instances of StorageError to be thrown and handled as part of Swift’s error-handling mechanism.

    See more

    Declaration

    Swift

    public enum StorageError : Error

  • Initializes a new instance of the StorageEngine class.

    Declaration

    Swift

    public init(
    path: String,
    compressionMethod: CompressionMethod = .none,
    fileProtectionType: FileProtectionType = .none

) throws

    Parameters

    path

    The file path where the storage engine will operate.
    compressionMethod

    The method used for compressing data. Defaults to .none.
    fileProtectionType

    The file protection level to apply. Defaults to .none.

  • Inserts a document into the specified collection in the storage engine.

    Throws

    An error if the insertion fails.

    Note

    This method is asynchronous and must be called with await.

    Declaration

    Swift

    public func insertDocument<T: Codable>(
    _ document: T,
    collection: String,
    indexField: String? = nil
) async throws

    Parameters

    document

    The document to be inserted. Must conform to the Codable protocol.
    collection

    The name of the collection where the document will be stored.
    indexField

    An optional field to be used as an index for the document. Defaults to nil.
  • fetchDocuments(from:) Asynchronous

    Fetches documents from the specified collection and decodes them into the specified type.

    This method retrieves all documents from the given collection and attempts to decode them into the specified Codable type T. The operation is asynchronous and may throw an error if the fetch or decoding process fails.

    Throws

    An error if the fetch operation or decoding process fails.

    Declaration

    Swift

    public func fetchDocuments<T: Codable>(from collection: String) async throws
    -> [T]

    Parameters

    collection

    The name of the collection to fetch documents from.

    Return Value

    An array of decoded objects of type T.

  • Fetches records from the specified collection that match the given field and value.

    This method performs an asynchronous operation to retrieve records from the index of the specified collection. The records are decoded into the specified generic type T.

    Throws

    An error if the fetch operation fails or if decoding the records fails.

    Declaration

    Swift

    public func fetchFromIndex<T: Codable>(
    collection: String,
    field: String,
    value: String
) async throws -> [T]

    Parameters

    collection

    The name of the collection to fetch records from.
    field

    The name of the field to match against.
    value

    The value to match in the specified field.

    Return Value

    An array of decoded objects of type T that match the specified criteria.

  • Fetches documents lazily from the specified collection.

    This method returns an AsyncThrowingStream that allows you to asynchronously iterate over the documents in the collection. Each document is decoded into the specified Codable type T.

    Throws

    An error if the operation fails during document retrieval or decoding.

    Declaration

    Swift

    public func fetchDocumentsLazy<T: Codable>(from collection: String)
    -> AsyncThrowingStream<T, Error>

    Parameters

    collection

    The name of the collection to fetch documents from.

    Return Value

    An AsyncThrowingStream of type T that provides asynchronous access to the documents in the collection.

  • Deletes documents from the specified collection that satisfy the given predicate.

    Throws

    An error if the deletion process fails.

    Note

    This method is asynchronous and must be called with await.

    Declaration

    Swift

    public func deleteDocuments<T: Codable>(
    where predicate: @escaping (T) -> Bool,
    from collection: String
) async throws

    Parameters

    predicate

    A closure that takes an instance of type T and returns a Boolean value indicating whether the document should be deleted.
    collection

    The name of the collection from which documents will be deleted.

  • Updates a document in the specified collection that matches the given predicate.

    Throws

    An error if the update operation fails.

    Note

    This method is asynchronous and must be called with await.

    Declaration

    Swift

    public func updateDocument<T: Codable>(
    _ document: T,
    in collection: String,
    matching predicate: (T) -> Bool,
    indexField: String? = nil
) async throws

    Parameters

    document

    The document of type T to update. Must conform to Codable.
    collection

    The name of the collection where the document resides.
    predicate

    A closure that takes a document of type T as its argument and returns a Boolean value indicating whether the document matches the criteria.
    indexField

    An optional field name to use as an index for optimizing the update operation.

  • Inserts multiple documents into the specified collection in bulk.

    Throws

    An error if the insertion fails.

    Note

    This method is asynchronous and must be called with await.

    Declaration

    Swift

    public func bulkInsertDocuments<T: Codable>(
    _ documents: [T],
    collection: String,
    indexField: String? = nil
) async throws

    Parameters

    documents

    An array of documents conforming to the Codable protocol to be inserted.
    collection

    The name of the collection where the documents will be inserted.
    indexField

    An optional field name to be used as an index for the documents. Defaults to nil.
  • countDocuments(in:) Asynchronous

    Counts the number of documents in the specified collection.

    Throws

    An error if the operation fails.

    Note

    This is an asynchronous method and must be called with await.

    Declaration

    Swift

    public func countDocuments(in collection: String) async throws -> Int

    Parameters

    collection

    The name of the collection to count documents in.

    Return Value

    The total number of documents in the specified collection.

  • dropCollection(_:) Asynchronous

    Drops the specified collection from the storage engine.

    This method removes all data associated with the given collection name.

    Throws

    An error if the operation fails.

    Note

    This operation is asynchronous and must be awaited.

    Declaration

    Swift

    public func dropCollection(_ collection: String) async throws

    Parameters

    collection

    The name of the collection to be dropped.

  • Lists all the collections available in the storage engine.

    Throws

    An error if the operation fails.

    Declaration

    Swift

    public func listCollections() throws -> [String]

    Return Value

    An array of strings representing the names of the collections.

  • getShardManagers(for:) Asynchronous

    Retrieves the shard managers associated with a specific collection.

    This asynchronous function fetches all the shards for the given collection name.

    Throws

    An error if the operation fails, such as issues with accessing the storage or invalid collection name.

    Declaration

    Swift

    public func getShardManagers(for collection: String) async throws -> [Shard]

    Parameters

    collection

    The name of the collection for which shard managers are to be retrieved.

    Return Value

    An array of Shard objects representing the shard managers for the specified collection.

  • Retrieves the shard associated with a specific partition within a given collection.

    Declaration

    Swift

    public func getShard(forPartition partition: String, in collection: String)
    async throws -> Shard?

    Parameters

    partition

    The identifier of the partition for which the shard is being retrieved.
    collection

    The name of the collection containing the partition.

  • Performs a bulk update of indexes for a specified collection.

    This method is asynchronous and allows for batch processing of index updates.

    Declaration

    Swift

    public func bulkUpdateIndexes(
    collection: String,
    updates: [(indexField: String, indexKey: String, data: Data)]
) async

    Parameters

    collection

    The name of the collection where the indexes will be updated.
    updates

    An array of tuples containing the index field, index key, and associated data to update.

  • Sets the partition key for a specified collection.

    Declaration

    Swift

    public func setPartitionKey(for collection: String, key: String)

    Parameters

    collection

    The name of the collection for which the partition key is being set.
    key

    The key to be used as the partition key for the collection.

  • Returns the directory URL for the specified collection.

    This method asynchronously retrieves the directory URL where the data for the given collection is stored.

    Throws

    An error if the directory cannot be determined or accessed.

    Declaration

    Swift

    public func collectionDirectory(for collection: String) async throws -> URL

    Parameters

    collection

    The name of the collection for which the directory URL is required.

    Return Value

    A URL pointing to the directory of the specified collection.

  • Repartitions a collection by changing its partition key.

    This method allows you to repartition an existing collection by specifying a new partition key. The operation is performed asynchronously and may throw an error if the operation fails.

    Throws

    An error if the repartitioning operation fails.

    Declaration

    Swift

    public func repartitionCollection<T: Codable>(
    collection: String,
    newPartitionKey: String,
    as type: T.Type
) async throws

    Parameters

    collection

    The name of the collection to repartition.
    newPartitionKey

    The new partition key to be used for the collection.
    type

    The type of the objects stored in the collection, conforming to Codable.

  • Undocumented

    Declaration

    Swift

    public func cleanupEmptyShards(for collection: String) async throws