slatedb.uniffi ============== .. py:module:: slatedb.uniffi .. autoapi-nested-parse:: Public Python wrapper for the generated SlateDB UniFFI bindings. Attributes ---------- .. autoapisummary:: slatedb.uniffi.Error slatedb.uniffi.MergeOperatorCallbackError Exceptions ---------- .. autoapisummary:: slatedb.uniffi.InternalError Classes ------- .. autoapisummary:: slatedb.uniffi.SourceId slatedb.uniffi.CompactionStatus slatedb.uniffi.SsTableId slatedb.uniffi.CompressionCodec slatedb.uniffi.SstType slatedb.uniffi.FilterFormat slatedb.uniffi.CloseReason slatedb.uniffi.FlushType slatedb.uniffi.LogLevel slatedb.uniffi.Ttl slatedb.uniffi.MetricValue slatedb.uniffi.DurabilityLevel slatedb.uniffi.FilterContext slatedb.uniffi.RowEntryKind slatedb.uniffi.IterationOrder slatedb.uniffi.CacheTarget slatedb.uniffi.IsolationLevel slatedb.uniffi.PrefixTarget slatedb.uniffi.SstBlockSize slatedb.uniffi.BloomFilterOptions slatedb.uniffi.Checkpoint slatedb.uniffi.CompactionSpec slatedb.uniffi.SsTableInfo slatedb.uniffi.SsTableHandle slatedb.uniffi.Compaction slatedb.uniffi.VersionedCompactions slatedb.uniffi.ExternalDb slatedb.uniffi.KeyRange slatedb.uniffi.SsTableView slatedb.uniffi.SortedRun slatedb.uniffi.VersionedManifest slatedb.uniffi.CompactorStateView slatedb.uniffi.DbStatus slatedb.uniffi.FlushOptions slatedb.uniffi.FoyerCacheOptions slatedb.uniffi.HistogramMetricValue slatedb.uniffi.KeyValue slatedb.uniffi.LogRecord slatedb.uniffi.MergeOptions slatedb.uniffi.MetricLabel slatedb.uniffi.Metric slatedb.uniffi.MokaCacheOptions slatedb.uniffi.PutOptions slatedb.uniffi.ReadOptions slatedb.uniffi.ReaderOptions slatedb.uniffi.RowEntry slatedb.uniffi.ScanOptions slatedb.uniffi.WalFileMetadata slatedb.uniffi.WriteHandle slatedb.uniffi.WriteOptions slatedb.uniffi.Admin slatedb.uniffi.AdminProtocol slatedb.uniffi.ObjectStore slatedb.uniffi.ObjectStoreProtocol slatedb.uniffi.AdminBuilder slatedb.uniffi.AdminBuilderProtocol slatedb.uniffi.CounterImpl slatedb.uniffi.Counter slatedb.uniffi.DbIterator slatedb.uniffi.DbIteratorProtocol slatedb.uniffi.DbTransaction slatedb.uniffi.DbTransactionProtocol slatedb.uniffi.DbSnapshot slatedb.uniffi.DbSnapshotProtocol slatedb.uniffi.WriteBatch slatedb.uniffi.WriteBatchProtocol slatedb.uniffi.Db slatedb.uniffi.DbProtocol slatedb.uniffi.DbCache slatedb.uniffi.DbCacheProtocol slatedb.uniffi.FilterPolicy slatedb.uniffi.FilterPolicyProtocol slatedb.uniffi.MergeOperatorImpl slatedb.uniffi.MergeOperator slatedb.uniffi.GaugeImpl slatedb.uniffi.Gauge slatedb.uniffi.UpDownCounterImpl slatedb.uniffi.UpDownCounter slatedb.uniffi.HistogramImpl slatedb.uniffi.Histogram slatedb.uniffi.MetricsRecorderImpl slatedb.uniffi.MetricsRecorder slatedb.uniffi.Settings slatedb.uniffi.SettingsProtocol slatedb.uniffi.DbBuilder slatedb.uniffi.DbBuilderProtocol slatedb.uniffi.DbReader slatedb.uniffi.DbReaderProtocol slatedb.uniffi.DbReaderBuilder slatedb.uniffi.DbReaderBuilderProtocol slatedb.uniffi.DefaultMetricsRecorder slatedb.uniffi.DefaultMetricsRecorderProtocol slatedb.uniffi.LogCallbackImpl slatedb.uniffi.LogCallback slatedb.uniffi.PrefixExtractorImpl slatedb.uniffi.PrefixExtractor slatedb.uniffi.WalFileIterator slatedb.uniffi.WalFileIteratorProtocol slatedb.uniffi.WalFile slatedb.uniffi.WalFileProtocol slatedb.uniffi.WalReader slatedb.uniffi.WalReaderProtocol Functions --------- .. autoapisummary:: slatedb.uniffi.init_logging Package Contents ---------------- .. py:exception:: InternalError Bases: :py:obj:`Exception` Common base class for all non-exit exceptions. .. py:class:: SourceId Compaction input source identifier. .. py:class:: SORTED_RUN(*values) Existing sorted run ID. .. py:class:: SST_VIEW(*values) L0 SST view ULID string. .. py:method:: is_SORTED_RUN() -> bool .. py:method:: is_sorted_run() -> bool .. py:method:: is_SST_VIEW() -> bool .. py:method:: is_sst_view() -> bool .. py:class:: CompactionStatus(*args, **kwds) Bases: :py:obj:`enum.Enum` Compaction lifecycle state. .. py:attribute:: SUBMITTED :value: 0 .. py:attribute:: RUNNING :value: 1 .. py:attribute:: COMPLETED :value: 2 .. py:attribute:: FAILED :value: 3 .. py:attribute:: COMPACTED :value: 4 .. py:class:: SsTableId SSTable identifier. .. py:class:: WAL(*values) WAL SST identified by numeric WAL ID. .. py:class:: COMPACTED(*values) Compacted SST identified by ULID string. .. py:method:: is_WAL() -> bool .. py:method:: is_wal() -> bool .. py:method:: is_COMPACTED() -> bool .. py:method:: is_compacted() -> bool .. py:class:: CompressionCodec(*args, **kwds) Bases: :py:obj:`enum.Enum` Compression codec used for an SSTable. .. py:attribute:: SNAPPY :value: 0 .. py:attribute:: ZLIB :value: 1 .. py:attribute:: LZ4 :value: 2 .. py:attribute:: ZSTD :value: 3 .. py:class:: SstType(*args, **kwds) Bases: :py:obj:`enum.Enum` Physical SSTable type. .. py:attribute:: COMPACTED :value: 0 .. py:attribute:: WAL :value: 1 .. py:class:: FilterFormat(*args, **kwds) Bases: :py:obj:`enum.Enum` Filter block format stored in SST metadata. .. py:attribute:: LEGACY :value: 0 .. py:attribute:: COMPOSITE :value: 1 .. py:class:: CloseReason(*args, **kwds) Bases: :py:obj:`enum.Enum` Reason a database or reader reports itself as closed. .. py:attribute:: CLEAN :value: 0 Closed cleanly by the caller. .. py:attribute:: FENCED :value: 1 Closed because another writer fenced this instance. .. py:attribute:: PANIC :value: 2 Closed because of a panic in a background task. .. py:attribute:: UNKNOWN :value: 3 Closed for a reason not modeled explicitly by this binding. .. py:class:: FlushType(*args, **kwds) Bases: :py:obj:`enum.Enum` Storage layer targeted by an explicit flush. .. py:attribute:: MEM_TABLE :value: 0 Flush the active memtable and any immutable memtables to object storage. .. py:attribute:: WAL :value: 1 Flush the active WAL and any immutable WAL segments to object storage. .. py:class:: LogLevel(*args, **kwds) Bases: :py:obj:`enum.Enum` Log level used by [`init_logging`]. .. py:attribute:: OFF :value: 0 Disable logging. .. py:attribute:: ERROR :value: 1 Error-level logs only. .. py:attribute:: WARN :value: 2 Warning and error logs. .. py:attribute:: INFO :value: 3 Info, warning, and error logs. .. py:attribute:: DEBUG :value: 4 Debug, info, warning, and error logs. .. py:attribute:: TRACE :value: 5 Trace and all higher-severity logs. .. py:class:: Ttl Time-to-live policy applied to an inserted value or merge operand. .. py:class:: DEFAULT Use the database default TTL. .. py:class:: NO_EXPIRY Store the value without expiration. .. py:class:: EXPIRE_AFTER_TICKS(*values) Expire the value after the given number of clock ticks. .. py:class:: EXPIRE_AT(*values) Expire the value at the given absolute timestamp (clock ticks). .. py:method:: is_DEFAULT() -> bool .. py:method:: is_default() -> bool .. py:method:: is_NO_EXPIRY() -> bool .. py:method:: is_no_expiry() -> bool .. py:method:: is_EXPIRE_AFTER_TICKS() -> bool .. py:method:: is_expire_after_ticks() -> bool .. py:method:: is_EXPIRE_AT() -> bool .. py:method:: is_expire_at() -> bool .. py:class:: MetricValue Value stored in a metric snapshot. .. py:class:: COUNTER(*values) Monotonic counter value. .. py:class:: GAUGE(*values) Gauge value. .. py:class:: UP_DOWN_COUNTER(*values) Up/down counter value. .. py:class:: HISTOGRAM(*values) Histogram summary and buckets. .. py:method:: is_COUNTER() -> bool .. py:method:: is_counter() -> bool .. py:method:: is_GAUGE() -> bool .. py:method:: is_gauge() -> bool .. py:method:: is_UP_DOWN_COUNTER() -> bool .. py:method:: is_up_down_counter() -> bool .. py:method:: is_HISTOGRAM() -> bool .. py:method:: is_histogram() -> bool .. py:class:: DurabilityLevel(*args, **kwds) Bases: :py:obj:`enum.Enum` Minimum durability level required for data returned by reads and scans. .. py:attribute:: REMOTE :value: 0 Return only data that has been flushed to remote object storage. .. py:attribute:: MEMORY :value: 1 Return both remote data and newer in-memory data. .. py:class:: FilterContext Opaque caller-supplied context forwarded to custom filter policies at query time. Custom filter policies read this to parametrize their evaluation; built-in policies (including the bloom filter) ignore it. The payload is opaque to SlateDB; the receiving policy is responsible for any decoding. .. py:class:: BYTES(payload: bytes) Variable-length payload. Maps to [`slatedb::FilterContext::Bytes`]. .. py:attribute:: payload .. py:method:: is_BYTES() -> bool .. py:method:: is_bytes() -> bool .. py:class:: RowEntryKind(*args, **kwds) Bases: :py:obj:`enum.Enum` Kind of row entry stored in WAL iteration results. .. py:attribute:: VALUE :value: 0 A regular value row. .. py:attribute:: TOMBSTONE :value: 1 A delete tombstone. .. py:attribute:: MERGE :value: 2 A merge operand row. .. py:class:: IterationOrder(*args, **kwds) Bases: :py:obj:`enum.Enum` The iteration order for a scan. .. py:attribute:: ASCENDING :value: 0 .. py:attribute:: DESCENDING :value: 1 .. py:class:: CacheTarget Cache content that [`crate::Db::warm_sst`] should populate. .. py:class:: FILTERS Warm all filters on the SST, if any exist. .. py:class:: INDEX Warm the SST index. .. py:class:: STATS Warm the SST stats block, if one exists. .. py:class:: DATA(range: KeyRange) Warm the SST data blocks that overlap `range`. Also warms the index, since block planning depends on it. .. py:attribute:: range .. py:method:: is_FILTERS() -> bool .. py:method:: is_filters() -> bool .. py:method:: is_INDEX() -> bool .. py:method:: is_index() -> bool .. py:method:: is_STATS() -> bool .. py:method:: is_stats() -> bool .. py:method:: is_DATA() -> bool .. py:method:: is_data() -> bool .. py:data:: Error .. py:class:: IsolationLevel(*args, **kwds) Bases: :py:obj:`enum.Enum` Isolation level used when starting a transaction. .. py:attribute:: SNAPSHOT :value: 0 Reads see a stable snapshot without full serializable conflict checking. .. py:attribute:: SERIALIZABLE_SNAPSHOT :value: 1 Reads see a stable snapshot with serializable conflict detection. .. py:data:: MergeOperatorCallbackError .. py:class:: PrefixTarget Identifies the target of a [`PrefixExtractor::prefix_len`] query. .. py:class:: POINT(key: bytes) A complete key, supplied either during SST construction or a point lookup. .. py:attribute:: key .. py:class:: PREFIX(prefix: bytes) A scan prefix supplied during a prefix scan. .. py:attribute:: prefix .. py:method:: is_POINT() -> bool .. py:method:: is_point() -> bool .. py:method:: is_PREFIX() -> bool .. py:method:: is_prefix() -> bool .. py:class:: SstBlockSize(*args, **kwds) Bases: :py:obj:`enum.Enum` Block size used for newly written SSTable blocks. .. py:attribute:: BLOCK1_KIB :value: 0 1 KiB blocks. .. py:attribute:: BLOCK2_KIB :value: 1 2 KiB blocks. .. py:attribute:: BLOCK4_KIB :value: 2 4 KiB blocks. .. py:attribute:: BLOCK8_KIB :value: 3 8 KiB blocks. .. py:attribute:: BLOCK16_KIB :value: 4 16 KiB blocks. .. py:attribute:: BLOCK32_KIB :value: 5 32 KiB blocks. .. py:attribute:: BLOCK64_KIB :value: 6 64 KiB blocks. .. py:class:: BloomFilterOptions(*, bits_per_key: int, whole_key_filtering: bool = True) Options controlling how a bloom filter policy is constructed. Pass an optional prefix extractor as a separate constructor parameter; it is kept out of this record because uniffi cannot marshal a trait object inside a record across every target language. .. py:attribute:: bits_per_key .. py:attribute:: whole_key_filtering :value: True .. py:class:: Checkpoint(*, id: str, manifest_id: int, expire_time_secs: Optional[int], create_time_secs: int, name: Optional[str]) Checkpoint metadata stored in a manifest. .. py:attribute:: id .. py:attribute:: manifest_id .. py:attribute:: expire_time_secs .. py:attribute:: create_time_secs .. py:attribute:: name .. py:class:: CompactionSpec(*, sources: List[SourceId], destination: Optional[int], has_l0_sources: bool, has_sr_sources: bool) Immutable compaction specification. .. py:attribute:: sources .. py:attribute:: destination .. py:attribute:: has_l0_sources .. py:attribute:: has_sr_sources .. py:class:: SsTableInfo(*, first_entry: Optional[bytes], last_entry: Optional[bytes], index_offset: int, index_len: int, filter_offset: int, filter_len: int, compression_codec: Optional[CompressionCodec], sst_type: SstType, stats_offset: int, stats_len: int, filter_format: FilterFormat) SSTable metadata. .. py:attribute:: first_entry .. py:attribute:: last_entry .. py:attribute:: index_offset .. py:attribute:: index_len .. py:attribute:: filter_offset .. py:attribute:: filter_len .. py:attribute:: compression_codec .. py:attribute:: sst_type .. py:attribute:: stats_offset .. py:attribute:: stats_len .. py:attribute:: filter_format .. py:class:: SsTableHandle(*, id: SsTableId, info: SsTableInfo, estimated_size_bytes: int) A handle to a physical SSTable. .. py:attribute:: id .. py:attribute:: info .. py:attribute:: estimated_size_bytes .. py:class:: Compaction(*, id: str, spec: CompactionSpec, bytes_processed: int, status: CompactionStatus, output_ssts: List[SsTableHandle], active: bool) Canonical compaction record. .. py:attribute:: id .. py:attribute:: spec .. py:attribute:: bytes_processed .. py:attribute:: status .. py:attribute:: output_ssts .. py:attribute:: active .. py:class:: VersionedCompactions(*, id: int, compactor_epoch: int, recent_compactions: List[Compaction]) A compactions snapshot paired with its version ID. .. py:attribute:: id .. py:attribute:: compactor_epoch .. py:attribute:: recent_compactions .. py:class:: ExternalDb(*, path: str, source_checkpoint_id: str, final_checkpoint_id: Optional[str], sst_ids: List[SsTableId]) External DB reference recorded in a manifest. .. py:attribute:: path .. py:attribute:: source_checkpoint_id .. py:attribute:: final_checkpoint_id .. py:attribute:: sst_ids .. py:class:: KeyRange(*, start: Optional[bytes], start_inclusive: bool, end: Optional[bytes], end_inclusive: bool) A half-open or closed byte-key range used by scan APIs. .. py:attribute:: start .. py:attribute:: start_inclusive .. py:attribute:: end .. py:attribute:: end_inclusive .. py:class:: SsTableView(*, id: str, sst: SsTableHandle, visible_range: Optional[KeyRange], estimated_size_bytes: int) Projected SST view used by manifests and sorted runs. .. py:attribute:: id .. py:attribute:: sst .. py:attribute:: visible_range .. py:attribute:: estimated_size_bytes .. py:class:: SortedRun(*, id: int, sst_views: List[SsTableView], estimated_size_bytes: int) A sorted run made up of one or more SST views. .. py:attribute:: id .. py:attribute:: sst_views .. py:attribute:: estimated_size_bytes .. py:class:: VersionedManifest(*, id: int, writer_epoch: int, compactor_epoch: int, external_dbs: List[ExternalDb], initialized: bool, last_compacted_l0_sst_view_id: Optional[str], last_compacted_l0_sst_id: Optional[str], l0: List[SsTableView], compacted: List[SortedRun], next_wal_sst_id: int, replay_after_wal_id: int, last_l0_clock_tick: int, last_l0_seq: int, recent_snapshot_min_seq: int, checkpoints: List[Checkpoint], wal_object_store_uri: Optional[str]) A manifest snapshot paired with its version ID. .. py:attribute:: id .. py:attribute:: writer_epoch .. py:attribute:: compactor_epoch .. py:attribute:: external_dbs .. py:attribute:: initialized .. py:attribute:: last_compacted_l0_sst_view_id .. py:attribute:: last_compacted_l0_sst_id .. py:attribute:: l0 .. py:attribute:: compacted .. py:attribute:: next_wal_sst_id .. py:attribute:: replay_after_wal_id .. py:attribute:: last_l0_clock_tick .. py:attribute:: last_l0_seq .. py:attribute:: recent_snapshot_min_seq .. py:attribute:: checkpoints .. py:attribute:: wal_object_store_uri .. py:class:: CompactorStateView(*, compactions: Optional[VersionedCompactions], manifest: VersionedManifest) Read-only compactor state view. .. py:attribute:: compactions .. py:attribute:: manifest .. py:class:: DbStatus(*, durable_seq: int, close_reason: Optional[CloseReason]) Snapshot of the current database lifecycle and durability state. .. py:attribute:: durable_seq .. py:attribute:: close_reason .. py:class:: FlushOptions(*, flush_type: FlushType) Options for an explicit flush request. .. py:attribute:: flush_type .. py:class:: FoyerCacheOptions(*, max_capacity: int, shards: int) Options for configuring Foyer DB cache. .. py:attribute:: max_capacity .. py:attribute:: shards .. py:class:: HistogramMetricValue(*, count: int, sum: float, min: float, max: float, boundaries: List[float], bucket_counts: List[int]) Histogram payload captured in a metric snapshot. .. py:attribute:: count .. py:attribute:: sum .. py:attribute:: min .. py:attribute:: max .. py:attribute:: boundaries .. py:attribute:: bucket_counts .. py:class:: KeyValue(*, key: bytes, value: bytes, seq: int, create_ts: int, expire_ts: Optional[int]) A key/value pair together with the row version metadata that produced it. .. py:attribute:: key .. py:attribute:: value .. py:attribute:: seq .. py:attribute:: create_ts .. py:attribute:: expire_ts .. py:class:: LogRecord(*, level: LogLevel, target: str, message: str, module_path: Optional[str], file: Optional[str], line: Optional[int]) A single log event forwarded to a foreign callback. .. py:attribute:: level .. py:attribute:: target .. py:attribute:: message .. py:attribute:: module_path .. py:attribute:: file .. py:attribute:: line .. py:class:: MergeOptions(*, ttl: Ttl) Options applied to a merge operation. .. py:attribute:: ttl .. py:class:: MetricLabel(*, key: str, value: str) Key-value label attached to a metric. .. py:attribute:: key .. py:attribute:: value .. py:class:: Metric(*, name: str, labels: List[MetricLabel], description: str, value: MetricValue) One metric from a [`DefaultMetricsRecorder`] snapshot. .. py:attribute:: name .. py:attribute:: labels .. py:attribute:: description .. py:attribute:: value .. py:class:: MokaCacheOptions(*, max_capacity: int, time_to_live: Optional[int], time_to_idle: Optional[int]) Options for configuring Moka DB cache. .. py:attribute:: max_capacity .. py:attribute:: time_to_live .. py:attribute:: time_to_idle .. py:class:: PutOptions(*, ttl: Ttl) Options applied to a put operation. .. py:attribute:: ttl .. py:class:: ReadOptions(*, durability_filter: DurabilityLevel, dirty: bool, cache_blocks: bool, filter_context: Optional[FilterContext] = _DEFAULT) Options that control a point read. .. py:attribute:: durability_filter .. py:attribute:: dirty .. py:attribute:: cache_blocks .. py:class:: ReaderOptions(*, manifest_poll_interval_ms: int, checkpoint_lifetime_ms: int, max_memtable_bytes: int, skip_wal_replay: bool) Options for opening a [`crate::DbReader`]. .. py:attribute:: manifest_poll_interval_ms .. py:attribute:: checkpoint_lifetime_ms .. py:attribute:: max_memtable_bytes .. py:attribute:: skip_wal_replay .. py:class:: RowEntry(*, kind: RowEntryKind, key: bytes, value: Optional[bytes], seq: int, create_ts: Optional[int], expire_ts: Optional[int]) A raw row entry returned from WAL inspection. .. py:attribute:: kind .. py:attribute:: key .. py:attribute:: value .. py:attribute:: seq .. py:attribute:: create_ts .. py:attribute:: expire_ts .. py:class:: ScanOptions(*, durability_filter: DurabilityLevel, dirty: bool, read_ahead_bytes: int, cache_blocks: bool, max_fetch_tasks: int, order: Optional[IterationOrder] = _DEFAULT, filter_context: Optional[FilterContext] = _DEFAULT) Options that control range scans and prefix scans. .. py:attribute:: durability_filter .. py:attribute:: dirty .. py:attribute:: read_ahead_bytes .. py:attribute:: cache_blocks .. py:attribute:: max_fetch_tasks .. py:class:: WalFileMetadata(*, last_modified_seconds: int, last_modified_nanos: int, size_bytes: int, location: str) Metadata describing a WAL file in object storage. .. py:attribute:: last_modified_seconds .. py:attribute:: last_modified_nanos .. py:attribute:: size_bytes .. py:attribute:: location .. py:class:: WriteHandle(*, seqnum: int, create_ts: int) Metadata returned by a successful write. .. py:attribute:: seqnum .. py:attribute:: create_ts .. py:class:: WriteOptions(*, await_durable: bool) Options that control durability behavior for writes and commits. .. py:attribute:: await_durable .. py:function:: init_logging(level: LogLevel, callback: Optional[LogCallback]) -> None Installs SlateDB logging exactly once for the current process. If `callback` is provided, log records are forwarded to it. Otherwise logs are written to standard error using the default tracing formatter. .. py:class:: Admin(*args, **kwargs) Bases: :py:obj:`AdminProtocol` Administrative read/query handle for SlateDB. .. py:method:: get_sequence_for_timestamp(timestamp_secs: int, round_up: bool) -> Optional[int] :async: Looks up a sequence number for the provided Unix UTC timestamp seconds. .. py:method:: get_timestamp_for_sequence(seq: int, round_up: bool) -> Optional[int] :async: Looks up a timestamp for the provided sequence number. .. py:method:: list_checkpoints(name_filter: Optional[str]) -> List[Checkpoint] :async: Lists checkpoints, optionally filtering by exact name. .. py:method:: list_compactions(_from: Optional[int], to: Optional[int]) -> List[VersionedCompactions] :async: Lists compactions files inside the half-open ID range `[from, to)`. .. py:method:: list_manifests(_from: Optional[int], to: Optional[int]) -> List[VersionedManifest] :async: Lists manifests inside the half-open ID range `[from, to)`. .. py:method:: read_compaction(compaction_id: str, compactions_id: Optional[int]) -> Optional[Compaction] :async: Reads a compaction by ULID string from a specific or latest compactions file. .. py:method:: read_compactions(id: Optional[int]) -> Optional[VersionedCompactions] :async: Reads a specific compactions file by ID, or the latest when `id` is `None`. .. py:method:: read_compactor_state_view() -> CompactorStateView :async: Reads the latest compactor state view. .. py:method:: read_manifest(id: Optional[int]) -> Optional[VersionedManifest] :async: Reads a specific manifest by ID, or the latest when `id` is `None`. .. py:class:: AdminProtocol Bases: :py:obj:`Protocol` Administrative read/query handle for SlateDB. .. py:method:: get_sequence_for_timestamp(timestamp_secs: int, round_up: bool) -> Optional[int] :abstractmethod: :async: Looks up a sequence number for the provided Unix UTC timestamp seconds. .. py:method:: get_timestamp_for_sequence(seq: int, round_up: bool) -> Optional[int] :abstractmethod: :async: Looks up a timestamp for the provided sequence number. .. py:method:: list_checkpoints(name_filter: Optional[str]) -> List[Checkpoint] :abstractmethod: :async: Lists checkpoints, optionally filtering by exact name. .. py:method:: list_compactions(_from: Optional[int], to: Optional[int]) -> List[VersionedCompactions] :abstractmethod: :async: Lists compactions files inside the half-open ID range `[from, to)`. .. py:method:: list_manifests(_from: Optional[int], to: Optional[int]) -> List[VersionedManifest] :abstractmethod: :async: Lists manifests inside the half-open ID range `[from, to)`. .. py:method:: read_compaction(compaction_id: str, compactions_id: Optional[int]) -> Optional[Compaction] :abstractmethod: :async: Reads a compaction by ULID string from a specific or latest compactions file. .. py:method:: read_compactions(id: Optional[int]) -> Optional[VersionedCompactions] :abstractmethod: :async: Reads a specific compactions file by ID, or the latest when `id` is `None`. .. py:method:: read_compactor_state_view() -> CompactorStateView :abstractmethod: :async: Reads the latest compactor state view. .. py:method:: read_manifest(id: Optional[int]) -> Optional[VersionedManifest] :abstractmethod: :async: Reads a specific manifest by ID, or the latest when `id` is `None`. .. py:class:: ObjectStore(*args, **kwargs) Bases: :py:obj:`ObjectStoreProtocol` Object store handle used when opening databases, readers, and WAL readers. .. py:method:: from_env(env_file: Optional[str]) -> ObjectStore :classmethod: Builds an object store from environment configuration. When `env_file` is provided, environment variables are loaded from that file before constructing the store. .. py:method:: resolve(url: str) -> ObjectStore :classmethod: Resolves an object store from a URL understood by SlateDB. .. py:class:: ObjectStoreProtocol Bases: :py:obj:`Protocol` Object store handle used when opening databases, readers, and WAL readers. .. py:class:: AdminBuilder(path: str, object_store: ObjectStore) Bases: :py:obj:`AdminBuilderProtocol` Builder for opening an administrative [`crate::Admin`] handle. Builders are single-use: calling [`AdminBuilder::build`] consumes the builder. .. py:method:: build() -> Admin Builds the admin handle and consumes this builder. .. py:method:: with_seed(seed: int) -> None Sets the seed used for SlateDB's internal random number generation. .. py:method:: with_wal_object_store(wal_object_store: ObjectStore) -> None Uses a separate object store for WAL-backed administrative operations. .. py:class:: AdminBuilderProtocol Bases: :py:obj:`Protocol` Builder for opening an administrative [`crate::Admin`] handle. Builders are single-use: calling [`AdminBuilder::build`] consumes the builder. .. py:method:: build() -> Admin :abstractmethod: Builds the admin handle and consumes this builder. .. py:method:: with_seed(seed: int) -> None :abstractmethod: Sets the seed used for SlateDB's internal random number generation. .. py:method:: with_wal_object_store(wal_object_store: ObjectStore) -> None :abstractmethod: Uses a separate object store for WAL-backed administrative operations. .. py:class:: CounterImpl(*args, **kwargs) Bases: :py:obj:`Counter` Handle for a monotonic counter metric. .. py:method:: increment(value: int) -> None Adds `value` to the counter. .. py:class:: Counter Handle for a monotonic counter metric. .. py:method:: increment(value: int) -> None :abstractmethod: Adds `value` to the counter. .. py:class:: DbIterator(*args, **kwargs) Bases: :py:obj:`DbIteratorProtocol` Async iterator returned by scan APIs. .. py:method:: next() -> Optional[KeyValue] :async: Returns the next key/value pair from the iterator. .. py:method:: seek(key: bytes) -> None :async: Seeks the iterator to the first entry at or after `key`. .. py:class:: DbIteratorProtocol Bases: :py:obj:`Protocol` Async iterator returned by scan APIs. .. py:method:: next() -> Optional[KeyValue] :abstractmethod: :async: Returns the next key/value pair from the iterator. .. py:method:: seek(key: bytes) -> None :abstractmethod: :async: Seeks the iterator to the first entry at or after `key`. .. py:class:: DbTransaction(*args, **kwargs) Bases: :py:obj:`DbTransactionProtocol` Transaction handle returned by [`crate::Db::begin`]. A transaction becomes unusable after `commit`, `commit_with_options`, or `rollback`. .. py:method:: commit() -> Optional[WriteHandle] :async: Commits the transaction. Returns `None` when the transaction performed no writes. .. py:method:: commit_with_options(options: WriteOptions) -> Optional[WriteHandle] :async: Commits the transaction using custom write options. Returns `None` when the transaction performed no writes. .. py:method:: delete(key: bytes) -> None :async: Buffers a delete inside the transaction. .. py:method:: get(key: bytes) -> Optional[bytes] :async: Reads the value visible to this transaction for `key`. .. py:method:: get_key_value(key: bytes) -> Optional[KeyValue] :async: Reads the row version visible to this transaction for `key`. .. py:method:: get_key_value_with_options(key: bytes, options: ReadOptions) -> Optional[KeyValue] :async: Reads the row version visible to this transaction for `key` using custom options. .. py:method:: get_with_options(key: bytes, options: ReadOptions) -> Optional[bytes] :async: Reads the value visible to this transaction for `key` using custom read options. .. py:method:: id() -> str Returns the transaction identifier as a UUID string. .. py:method:: mark_read(keys: List[bytes]) -> None :async: Marks keys as read for conflict detection. .. py:method:: merge(key: bytes, operand: bytes) -> None :async: Buffers a merge operand inside the transaction. .. py:method:: merge_with_options(key: bytes, operand: bytes, options: MergeOptions) -> None :async: Buffers a merge operand inside the transaction using custom merge options. .. py:method:: put(key: bytes, value: bytes) -> None :async: Buffers a put inside the transaction. .. py:method:: put_with_options(key: bytes, value: bytes, options: PutOptions) -> None :async: Buffers a put inside the transaction using custom put options. .. py:method:: rollback() -> None :async: Rolls back the transaction and marks it completed. .. py:method:: scan(range: KeyRange) -> DbIterator :async: Scans rows inside `range` as visible to this transaction. .. py:method:: scan_prefix(prefix: bytes) -> DbIterator :async: Scans rows whose keys start with `prefix` as visible to this transaction. .. py:method:: scan_prefix_with_options(prefix: bytes, options: ScanOptions) -> DbIterator :async: Scans rows whose keys start with `prefix` as visible to this transaction using custom options. .. py:method:: scan_with_options(range: KeyRange, options: ScanOptions) -> DbIterator :async: Scans rows inside `range` as visible to this transaction using custom options. .. py:method:: seqnum() -> int Returns the sequence number assigned when the transaction started. .. py:method:: unmark_write(keys: List[bytes]) -> None :async: Excludes written keys from transaction conflict detection. .. py:class:: DbTransactionProtocol Bases: :py:obj:`Protocol` Transaction handle returned by [`crate::Db::begin`]. A transaction becomes unusable after `commit`, `commit_with_options`, or `rollback`. .. py:method:: commit() -> Optional[WriteHandle] :abstractmethod: :async: Commits the transaction. Returns `None` when the transaction performed no writes. .. py:method:: commit_with_options(options: WriteOptions) -> Optional[WriteHandle] :abstractmethod: :async: Commits the transaction using custom write options. Returns `None` when the transaction performed no writes. .. py:method:: delete(key: bytes) -> None :abstractmethod: :async: Buffers a delete inside the transaction. .. py:method:: get(key: bytes) -> Optional[bytes] :abstractmethod: :async: Reads the value visible to this transaction for `key`. .. py:method:: get_key_value(key: bytes) -> Optional[KeyValue] :abstractmethod: :async: Reads the row version visible to this transaction for `key`. .. py:method:: get_key_value_with_options(key: bytes, options: ReadOptions) -> Optional[KeyValue] :abstractmethod: :async: Reads the row version visible to this transaction for `key` using custom options. .. py:method:: get_with_options(key: bytes, options: ReadOptions) -> Optional[bytes] :abstractmethod: :async: Reads the value visible to this transaction for `key` using custom read options. .. py:method:: id() -> str :abstractmethod: Returns the transaction identifier as a UUID string. .. py:method:: mark_read(keys: List[bytes]) -> None :abstractmethod: :async: Marks keys as read for conflict detection. .. py:method:: merge(key: bytes, operand: bytes) -> None :abstractmethod: :async: Buffers a merge operand inside the transaction. .. py:method:: merge_with_options(key: bytes, operand: bytes, options: MergeOptions) -> None :abstractmethod: :async: Buffers a merge operand inside the transaction using custom merge options. .. py:method:: put(key: bytes, value: bytes) -> None :abstractmethod: :async: Buffers a put inside the transaction. .. py:method:: put_with_options(key: bytes, value: bytes, options: PutOptions) -> None :abstractmethod: :async: Buffers a put inside the transaction using custom put options. .. py:method:: rollback() -> None :abstractmethod: :async: Rolls back the transaction and marks it completed. .. py:method:: scan(range: KeyRange) -> DbIterator :abstractmethod: :async: Scans rows inside `range` as visible to this transaction. .. py:method:: scan_prefix(prefix: bytes) -> DbIterator :abstractmethod: :async: Scans rows whose keys start with `prefix` as visible to this transaction. .. py:method:: scan_prefix_with_options(prefix: bytes, options: ScanOptions) -> DbIterator :abstractmethod: :async: Scans rows whose keys start with `prefix` as visible to this transaction using custom options. .. py:method:: scan_with_options(range: KeyRange, options: ScanOptions) -> DbIterator :abstractmethod: :async: Scans rows inside `range` as visible to this transaction using custom options. .. py:method:: seqnum() -> int :abstractmethod: Returns the sequence number assigned when the transaction started. .. py:method:: unmark_write(keys: List[bytes]) -> None :abstractmethod: :async: Excludes written keys from transaction conflict detection. .. py:class:: DbSnapshot(*args, **kwargs) Bases: :py:obj:`DbSnapshotProtocol` Read-only snapshot representing a consistent view of the database. .. py:method:: get(key: bytes) -> Optional[bytes] :async: Reads the value visible in this snapshot for `key`. .. py:method:: get_key_value(key: bytes) -> Optional[KeyValue] :async: Reads the row version visible in this snapshot for `key`. .. py:method:: get_key_value_with_options(key: bytes, options: ReadOptions) -> Optional[KeyValue] :async: Reads the row version visible in this snapshot for `key` using custom read options. .. py:method:: get_with_options(key: bytes, options: ReadOptions) -> Optional[bytes] :async: Reads the value visible in this snapshot for `key` using custom read options. .. py:method:: scan(range: KeyRange) -> DbIterator :async: Scans rows inside `range` as of this snapshot. .. py:method:: scan_prefix(prefix: bytes) -> DbIterator :async: Scans rows whose keys start with `prefix` as of this snapshot. .. py:method:: scan_prefix_with_options(prefix: bytes, options: ScanOptions) -> DbIterator :async: Scans rows whose keys start with `prefix` as of this snapshot using custom options. .. py:method:: scan_with_options(range: KeyRange, options: ScanOptions) -> DbIterator :async: Scans rows inside `range` as of this snapshot using custom scan options. .. py:class:: DbSnapshotProtocol Bases: :py:obj:`Protocol` Read-only snapshot representing a consistent view of the database. .. py:method:: get(key: bytes) -> Optional[bytes] :abstractmethod: :async: Reads the value visible in this snapshot for `key`. .. py:method:: get_key_value(key: bytes) -> Optional[KeyValue] :abstractmethod: :async: Reads the row version visible in this snapshot for `key`. .. py:method:: get_key_value_with_options(key: bytes, options: ReadOptions) -> Optional[KeyValue] :abstractmethod: :async: Reads the row version visible in this snapshot for `key` using custom read options. .. py:method:: get_with_options(key: bytes, options: ReadOptions) -> Optional[bytes] :abstractmethod: :async: Reads the value visible in this snapshot for `key` using custom read options. .. py:method:: scan(range: KeyRange) -> DbIterator :abstractmethod: :async: Scans rows inside `range` as of this snapshot. .. py:method:: scan_prefix(prefix: bytes) -> DbIterator :abstractmethod: :async: Scans rows whose keys start with `prefix` as of this snapshot. .. py:method:: scan_prefix_with_options(prefix: bytes, options: ScanOptions) -> DbIterator :abstractmethod: :async: Scans rows whose keys start with `prefix` as of this snapshot using custom options. .. py:method:: scan_with_options(range: KeyRange, options: ScanOptions) -> DbIterator :abstractmethod: :async: Scans rows inside `range` as of this snapshot using custom scan options. .. py:class:: WriteBatch Bases: :py:obj:`WriteBatchProtocol` Mutable batch of write operations applied atomically by [`crate::Db::write`]. A batch is single-use once submitted to the database. .. py:method:: delete(key: bytes) -> None Appends a delete operation to the batch. .. py:method:: merge(key: bytes, operand: bytes) -> None Appends a merge operation to the batch. .. py:method:: merge_with_options(key: bytes, operand: bytes, options: MergeOptions) -> None Appends a merge operation with custom merge options. .. py:method:: put(key: bytes, value: bytes) -> None Appends a put operation to the batch. .. py:method:: put_with_options(key: bytes, value: bytes, options: PutOptions) -> None Appends a put operation with custom put options. .. py:class:: WriteBatchProtocol Bases: :py:obj:`Protocol` Mutable batch of write operations applied atomically by [`crate::Db::write`]. A batch is single-use once submitted to the database. .. py:method:: delete(key: bytes) -> None :abstractmethod: Appends a delete operation to the batch. .. py:method:: merge(key: bytes, operand: bytes) -> None :abstractmethod: Appends a merge operation to the batch. .. py:method:: merge_with_options(key: bytes, operand: bytes, options: MergeOptions) -> None :abstractmethod: Appends a merge operation with custom merge options. .. py:method:: put(key: bytes, value: bytes) -> None :abstractmethod: Appends a put operation to the batch. .. py:method:: put_with_options(key: bytes, value: bytes, options: PutOptions) -> None :abstractmethod: Appends a put operation with custom put options. .. py:class:: Db(*args, **kwargs) Bases: :py:obj:`DbProtocol` A writable SlateDB handle. .. py:method:: begin(isolation_level: IsolationLevel) -> DbTransaction :async: Starts a transaction at the requested isolation level. .. py:method:: delete(key: bytes) -> WriteHandle :async: Deletes `key` and returns metadata for the write. .. py:method:: delete_with_options(key: bytes, options: WriteOptions) -> WriteHandle :async: Deletes `key` using custom write options. .. py:method:: evict_cached_sst(sst_id: SsTableId) -> None :async: Best-effort eviction of block-cache entries for one SST. If no block cache is configured, returns `Ok(())`. .. py:method:: flush() -> None :async: Flushes the default storage layer. .. py:method:: flush_with_options(options: FlushOptions) -> None :async: Flushes according to the provided flush options. .. py:method:: get(key: bytes) -> Optional[bytes] :async: Reads the current value for `key`. .. py:method:: get_key_value(key: bytes) -> Optional[KeyValue] :async: Reads the current row version for `key`, including metadata. .. py:method:: get_key_value_with_options(key: bytes, options: ReadOptions) -> Optional[KeyValue] :async: Reads the current row version for `key` using custom read options. .. py:method:: get_with_options(key: bytes, options: ReadOptions) -> Optional[bytes] :async: Reads the current value for `key` using custom read options. .. py:method:: merge(key: bytes, operand: bytes) -> WriteHandle :async: Appends a merge operand for `key` and returns metadata for the write. .. py:method:: merge_with_options(key: bytes, operand: bytes, merge_options: MergeOptions, write_options: WriteOptions) -> WriteHandle :async: Appends a merge operand using custom merge and write options. .. py:method:: put(key: bytes, value: bytes) -> WriteHandle :async: Inserts or overwrites a value and returns metadata for the write. Keys must be non-empty and at most `u16::MAX` bytes. Values must be at most `u32::MAX` bytes. .. py:method:: put_with_options(key: bytes, value: bytes, put_options: PutOptions, write_options: WriteOptions) -> WriteHandle :async: Inserts or overwrites a value using custom put and write options. .. py:method:: scan(range: KeyRange) -> DbIterator :async: Scans rows inside `range`. .. py:method:: scan_prefix(prefix: bytes) -> DbIterator :async: Scans rows whose keys start with `prefix`. .. py:method:: scan_prefix_with_options(prefix: bytes, options: ScanOptions) -> DbIterator :async: Scans rows whose keys start with `prefix` using custom scan options. .. py:method:: scan_with_options(range: KeyRange, options: ScanOptions) -> DbIterator :async: Scans rows inside `range` using custom scan options. .. py:method:: shutdown() -> None :async: Flushes outstanding work and closes the database. .. py:method:: snapshot() -> DbSnapshot :async: Creates a read-only snapshot representing a consistent point in time. .. py:method:: status() -> DbStatus Returns the latest database status snapshot. .. py:method:: warm_sst(sst_id: SsTableId, targets: List[CacheTarget]) -> None :async: Warms selected cache content for one SST. Returns `Err` on the first failing target. If no block cache is configured, or if the SST is not reachable from the current manifest, the call is a no-op that returns `Ok(())`. .. py:method:: write(batch: WriteBatch) -> WriteHandle :async: Applies all operations in `batch` atomically. The provided batch is consumed and cannot be reused afterwards. .. py:method:: write_with_options(batch: WriteBatch, options: WriteOptions) -> WriteHandle :async: Applies all operations in `batch` atomically using custom write options. The provided batch is consumed and cannot be reused afterwards. .. py:class:: DbProtocol Bases: :py:obj:`Protocol` A writable SlateDB handle. .. py:method:: begin(isolation_level: IsolationLevel) -> DbTransaction :abstractmethod: :async: Starts a transaction at the requested isolation level. .. py:method:: delete(key: bytes) -> WriteHandle :abstractmethod: :async: Deletes `key` and returns metadata for the write. .. py:method:: delete_with_options(key: bytes, options: WriteOptions) -> WriteHandle :abstractmethod: :async: Deletes `key` using custom write options. .. py:method:: evict_cached_sst(sst_id: SsTableId) -> None :abstractmethod: :async: Best-effort eviction of block-cache entries for one SST. If no block cache is configured, returns `Ok(())`. .. py:method:: flush() -> None :abstractmethod: :async: Flushes the default storage layer. .. py:method:: flush_with_options(options: FlushOptions) -> None :abstractmethod: :async: Flushes according to the provided flush options. .. py:method:: get(key: bytes) -> Optional[bytes] :abstractmethod: :async: Reads the current value for `key`. .. py:method:: get_key_value(key: bytes) -> Optional[KeyValue] :abstractmethod: :async: Reads the current row version for `key`, including metadata. .. py:method:: get_key_value_with_options(key: bytes, options: ReadOptions) -> Optional[KeyValue] :abstractmethod: :async: Reads the current row version for `key` using custom read options. .. py:method:: get_with_options(key: bytes, options: ReadOptions) -> Optional[bytes] :abstractmethod: :async: Reads the current value for `key` using custom read options. .. py:method:: merge(key: bytes, operand: bytes) -> WriteHandle :abstractmethod: :async: Appends a merge operand for `key` and returns metadata for the write. .. py:method:: merge_with_options(key: bytes, operand: bytes, merge_options: MergeOptions, write_options: WriteOptions) -> WriteHandle :abstractmethod: :async: Appends a merge operand using custom merge and write options. .. py:method:: put(key: bytes, value: bytes) -> WriteHandle :abstractmethod: :async: Inserts or overwrites a value and returns metadata for the write. Keys must be non-empty and at most `u16::MAX` bytes. Values must be at most `u32::MAX` bytes. .. py:method:: put_with_options(key: bytes, value: bytes, put_options: PutOptions, write_options: WriteOptions) -> WriteHandle :abstractmethod: :async: Inserts or overwrites a value using custom put and write options. .. py:method:: scan(range: KeyRange) -> DbIterator :abstractmethod: :async: Scans rows inside `range`. .. py:method:: scan_prefix(prefix: bytes) -> DbIterator :abstractmethod: :async: Scans rows whose keys start with `prefix`. .. py:method:: scan_prefix_with_options(prefix: bytes, options: ScanOptions) -> DbIterator :abstractmethod: :async: Scans rows whose keys start with `prefix` using custom scan options. .. py:method:: scan_with_options(range: KeyRange, options: ScanOptions) -> DbIterator :abstractmethod: :async: Scans rows inside `range` using custom scan options. .. py:method:: shutdown() -> None :abstractmethod: :async: Flushes outstanding work and closes the database. .. py:method:: snapshot() -> DbSnapshot :abstractmethod: :async: Creates a read-only snapshot representing a consistent point in time. .. py:method:: status() -> DbStatus :abstractmethod: Returns the latest database status snapshot. .. py:method:: warm_sst(sst_id: SsTableId, targets: List[CacheTarget]) -> None :abstractmethod: :async: Warms selected cache content for one SST. Returns `Err` on the first failing target. If no block cache is configured, or if the SST is not reachable from the current manifest, the call is a no-op that returns `Ok(())`. .. py:method:: write(batch: WriteBatch) -> WriteHandle :abstractmethod: :async: Applies all operations in `batch` atomically. The provided batch is consumed and cannot be reused afterwards. .. py:method:: write_with_options(batch: WriteBatch, options: WriteOptions) -> WriteHandle :abstractmethod: :async: Applies all operations in `batch` atomically using custom write options. The provided batch is consumed and cannot be reused afterwards. .. py:class:: DbCache(*args, **kwargs) Bases: :py:obj:`DbCacheProtocol` Database cache used to store blocks in memory. .. py:method:: new_foyer_cache(options: FoyerCacheOptions) -> DbCache :classmethod: Creates a new Foyer based DB cache. .. py:method:: new_moka_cache(options: MokaCacheOptions) -> DbCache :classmethod: Creates a new Moka based DB cache. .. py:method:: new_split_cache(block_cache: DbCache, meta_cache: DbCache) -> DbCache :classmethod: Creates a new split cache with separate block and metadata capacities. .. py:class:: DbCacheProtocol Bases: :py:obj:`Protocol` Database cache used to store blocks in memory. .. py:class:: FilterPolicy(*args, **kwargs) Bases: :py:obj:`FilterPolicyProtocol` A filter policy used to build and read SST filters. Construct one with [`FilterPolicy::bloom`] or [`FilterPolicy::bloom_with_options`] for the built-in bloom filter. .. py:method:: bloom(bits_per_key: int) -> FilterPolicy :classmethod: Constructs a bloom filter policy with the given bits per key, whole-key filtering enabled, and no prefix extractor. .. py:method:: bloom_with_options(options: BloomFilterOptions, prefix_extractor: Optional[PrefixExtractor]) -> FilterPolicy :classmethod: Constructs a bloom filter policy from the supplied options, with an optional prefix extractor enabling prefix-based bloom filtering. .. py:method:: name() -> str Returns the policy name encoded into SSTs that use this policy. .. py:class:: FilterPolicyProtocol Bases: :py:obj:`Protocol` A filter policy used to build and read SST filters. Construct one with [`FilterPolicy::bloom`] or [`FilterPolicy::bloom_with_options`] for the built-in bloom filter. .. py:method:: name() -> str :abstractmethod: Returns the policy name encoded into SSTs that use this policy. .. py:class:: MergeOperatorImpl(*args, **kwargs) Bases: :py:obj:`MergeOperator` Application-provided merge operator used by merge-enabled databases. .. py:method:: merge(key: bytes, existing_value: Optional[bytes], operand: bytes) -> bytes Combines an existing value and a new merge operand into the next value. `existing_value` is `None` when the key has no visible base value. .. py:class:: MergeOperator Application-provided merge operator used by merge-enabled databases. .. py:method:: merge(key: bytes, existing_value: Optional[bytes], operand: bytes) -> bytes :abstractmethod: Combines an existing value and a new merge operand into the next value. `existing_value` is `None` when the key has no visible base value. .. py:class:: GaugeImpl(*args, **kwargs) Bases: :py:obj:`Gauge` Handle for a gauge metric. .. py:method:: set(value: int) -> None Sets the gauge to `value`. .. py:class:: Gauge Handle for a gauge metric. .. py:method:: set(value: int) -> None :abstractmethod: Sets the gauge to `value`. .. py:class:: UpDownCounterImpl(*args, **kwargs) Bases: :py:obj:`UpDownCounter` Handle for an up/down counter metric. .. py:method:: increment(value: int) -> None Adds `value` to the counter. .. py:class:: UpDownCounter Handle for an up/down counter metric. .. py:method:: increment(value: int) -> None :abstractmethod: Adds `value` to the counter. .. py:class:: HistogramImpl(*args, **kwargs) Bases: :py:obj:`Histogram` Handle for a histogram metric. .. py:method:: record(value: float) -> None Records `value` in the histogram. .. py:class:: Histogram Handle for a histogram metric. .. py:method:: record(value: float) -> None :abstractmethod: Records `value` in the histogram. .. py:class:: MetricsRecorderImpl(*args, **kwargs) Bases: :py:obj:`MetricsRecorder` Application-defined metrics recorder used to publish SlateDB metrics. .. py:method:: register_counter(name: str, description: Optional[str], labels: List[MetricLabel]) -> Counter Registers a monotonically increasing counter. .. py:method:: register_gauge(name: str, description: Optional[str], labels: List[MetricLabel]) -> Gauge Registers a gauge. .. py:method:: register_up_down_counter(name: str, description: Optional[str], labels: List[MetricLabel]) -> UpDownCounter Registers an up/down counter. .. py:method:: register_histogram(name: str, description: Optional[str], labels: List[MetricLabel], boundaries: List[float]) -> Histogram Registers a histogram with explicit bucket boundaries. .. py:class:: MetricsRecorder Application-defined metrics recorder used to publish SlateDB metrics. .. py:method:: register_counter(name: str, description: Optional[str], labels: List[MetricLabel]) -> Counter :abstractmethod: Registers a monotonically increasing counter. .. py:method:: register_gauge(name: str, description: Optional[str], labels: List[MetricLabel]) -> Gauge :abstractmethod: Registers a gauge. .. py:method:: register_up_down_counter(name: str, description: Optional[str], labels: List[MetricLabel]) -> UpDownCounter :abstractmethod: Registers an up/down counter. .. py:method:: register_histogram(name: str, description: Optional[str], labels: List[MetricLabel], boundaries: List[float]) -> Histogram :abstractmethod: Registers a histogram with explicit bucket boundaries. .. py:class:: Settings(*args, **kwargs) Bases: :py:obj:`SettingsProtocol` Mutable database settings object used to configure a [`crate::DbBuilder`]. .. py:method:: default() -> Settings :classmethod: Creates a settings object populated with SlateDB defaults. .. py:method:: from_env(prefix: str) -> Settings :classmethod: Loads settings from environment variables using `prefix`. .. py:method:: from_env_with_default(prefix: str, default_settings: Settings) -> Settings :classmethod: Loads settings from environment variables, falling back to `default_settings`. .. py:method:: from_file(path: str) -> Settings :classmethod: Loads settings from a JSON, TOML, or YAML file based on its extension. .. py:method:: from_json_string(json: str) -> Settings :classmethod: Parses settings from a JSON string. .. py:method:: load() -> Settings :classmethod: Loads settings from SlateDB's default file and environment lookup order. .. py:method:: set(key: str, value_json: str) -> None Sets a settings field by dotted path using a JSON literal value. `key` identifies the field to update. Use `.` to address nested objects, for example `compactor_options.max_sst_size` or `object_store_cache_options.root_folder`. `value_json` must be a valid JSON literal matching the target field's expected type. That means strings must be quoted JSON strings, numbers should be passed as JSON numbers, booleans as `true`/`false`, and optional fields can be cleared with `null`. Missing or `null` intermediate objects in the dotted path are created automatically. If the update would produce an invalid `slatedb::Settings` value, the method returns an error and leaves the current settings unchanged. Examples: - `set("flush_interval", ""250ms"")` - `set("default_ttl", "42")` - `set("default_ttl", "null")` - `set("compactor_options.max_sst_size", "33554432")` - `set("object_store_cache_options.root_folder", ""/tmp/slatedb-cache"")` .. py:method:: to_json_string() -> str Serializes the current settings value to a JSON string. .. py:class:: SettingsProtocol Bases: :py:obj:`Protocol` Mutable database settings object used to configure a [`crate::DbBuilder`]. .. py:method:: set(key: str, value_json: str) -> None :abstractmethod: Sets a settings field by dotted path using a JSON literal value. `key` identifies the field to update. Use `.` to address nested objects, for example `compactor_options.max_sst_size` or `object_store_cache_options.root_folder`. `value_json` must be a valid JSON literal matching the target field's expected type. That means strings must be quoted JSON strings, numbers should be passed as JSON numbers, booleans as `true`/`false`, and optional fields can be cleared with `null`. Missing or `null` intermediate objects in the dotted path are created automatically. If the update would produce an invalid `slatedb::Settings` value, the method returns an error and leaves the current settings unchanged. Examples: - `set("flush_interval", ""250ms"")` - `set("default_ttl", "42")` - `set("default_ttl", "null")` - `set("compactor_options.max_sst_size", "33554432")` - `set("object_store_cache_options.root_folder", ""/tmp/slatedb-cache"")` .. py:method:: to_json_string() -> str :abstractmethod: Serializes the current settings value to a JSON string. .. py:class:: DbBuilder(path: str, object_store: ObjectStore) Bases: :py:obj:`DbBuilderProtocol` Builder for opening a writable [`crate::Db`]. Builders are single-use: calling [`DbBuilder::build`] consumes the builder. .. py:method:: build() -> Db :async: Opens the database and consumes this builder. .. py:method:: with_db_cache(db_cache: DbCache) -> None Sets DB cache. .. py:method:: with_db_cache_disabled() -> None Disables the SST block and metadata cache. .. py:method:: with_filter_policies(policies: List[FilterPolicy]) -> None Sets the filter policies used for SST filter construction and evaluation. Pass an empty vec to disable filters entirely. When unset, the default is a single bloom filter with 10 bits per key. .. py:method:: with_merge_operator(merge_operator: MergeOperator) -> None Installs an application-defined merge operator. .. py:method:: with_metrics_recorder(metrics_recorder: MetricsRecorder) -> None Installs an application-defined metrics recorder. .. py:method:: with_seed(seed: int) -> None Sets the seed used for SlateDB's internal random number generation. .. py:method:: with_settings(settings: Settings) -> None Applies a [`crate::Settings`] object to the builder. .. py:method:: with_sst_block_size(sst_block_size: SstBlockSize) -> None Sets the SSTable block size used for newly written tables. .. py:method:: with_wal_object_store(wal_object_store: ObjectStore) -> None Uses a separate object store for WAL files. .. py:class:: DbBuilderProtocol Bases: :py:obj:`Protocol` Builder for opening a writable [`crate::Db`]. Builders are single-use: calling [`DbBuilder::build`] consumes the builder. .. py:method:: build() -> Db :abstractmethod: :async: Opens the database and consumes this builder. .. py:method:: with_db_cache(db_cache: DbCache) -> None :abstractmethod: Sets DB cache. .. py:method:: with_db_cache_disabled() -> None :abstractmethod: Disables the SST block and metadata cache. .. py:method:: with_filter_policies(policies: List[FilterPolicy]) -> None :abstractmethod: Sets the filter policies used for SST filter construction and evaluation. Pass an empty vec to disable filters entirely. When unset, the default is a single bloom filter with 10 bits per key. .. py:method:: with_merge_operator(merge_operator: MergeOperator) -> None :abstractmethod: Installs an application-defined merge operator. .. py:method:: with_metrics_recorder(metrics_recorder: MetricsRecorder) -> None :abstractmethod: Installs an application-defined metrics recorder. .. py:method:: with_seed(seed: int) -> None :abstractmethod: Sets the seed used for SlateDB's internal random number generation. .. py:method:: with_settings(settings: Settings) -> None :abstractmethod: Applies a [`crate::Settings`] object to the builder. .. py:method:: with_sst_block_size(sst_block_size: SstBlockSize) -> None :abstractmethod: Sets the SSTable block size used for newly written tables. .. py:method:: with_wal_object_store(wal_object_store: ObjectStore) -> None :abstractmethod: Uses a separate object store for WAL files. .. py:class:: DbReader(*args, **kwargs) Bases: :py:obj:`DbReaderProtocol` Read-only database handle opened by [`crate::DbReaderBuilder`]. .. py:method:: evict_cached_sst(sst_id: SsTableId) -> None :async: Best-effort eviction of block-cache entries for one SST. If no block cache is configured, returns `Ok(())`. .. py:method:: get(key: bytes) -> Optional[bytes] :async: Reads the current value for `key`. .. py:method:: get_key_value(key: bytes) -> Optional[KeyValue] :async: Reads the current row version for `key`, including metadata. .. py:method:: get_key_value_with_options(key: bytes, options: ReadOptions) -> Optional[KeyValue] :async: Reads the current row version for `key` using custom read options. .. py:method:: get_with_options(key: bytes, options: ReadOptions) -> Optional[bytes] :async: Reads the current value for `key` using custom read options. .. py:method:: scan(range: KeyRange) -> DbIterator :async: Scans rows inside `range`. .. py:method:: scan_prefix(prefix: bytes) -> DbIterator :async: Scans rows whose keys start with `prefix`. .. py:method:: scan_prefix_with_options(prefix: bytes, options: ScanOptions) -> DbIterator :async: Scans rows whose keys start with `prefix` using custom scan options. .. py:method:: scan_with_options(range: KeyRange, options: ScanOptions) -> DbIterator :async: Scans rows inside `range` using custom scan options. .. py:method:: shutdown() -> None :async: Closes the reader. .. py:method:: status() -> DbStatus Returns the latest reader status snapshot. .. py:method:: warm_sst(sst_id: SsTableId, targets: List[CacheTarget]) -> None :async: Warms selected cache content for one SST. Returns `Err` on the first failing target. If no block cache is configured, or if the SST is not reachable from the current manifest, the call is a no-op that returns `Ok(())`. .. py:class:: DbReaderProtocol Bases: :py:obj:`Protocol` Read-only database handle opened by [`crate::DbReaderBuilder`]. .. py:method:: evict_cached_sst(sst_id: SsTableId) -> None :abstractmethod: :async: Best-effort eviction of block-cache entries for one SST. If no block cache is configured, returns `Ok(())`. .. py:method:: get(key: bytes) -> Optional[bytes] :abstractmethod: :async: Reads the current value for `key`. .. py:method:: get_key_value(key: bytes) -> Optional[KeyValue] :abstractmethod: :async: Reads the current row version for `key`, including metadata. .. py:method:: get_key_value_with_options(key: bytes, options: ReadOptions) -> Optional[KeyValue] :abstractmethod: :async: Reads the current row version for `key` using custom read options. .. py:method:: get_with_options(key: bytes, options: ReadOptions) -> Optional[bytes] :abstractmethod: :async: Reads the current value for `key` using custom read options. .. py:method:: scan(range: KeyRange) -> DbIterator :abstractmethod: :async: Scans rows inside `range`. .. py:method:: scan_prefix(prefix: bytes) -> DbIterator :abstractmethod: :async: Scans rows whose keys start with `prefix`. .. py:method:: scan_prefix_with_options(prefix: bytes, options: ScanOptions) -> DbIterator :abstractmethod: :async: Scans rows whose keys start with `prefix` using custom scan options. .. py:method:: scan_with_options(range: KeyRange, options: ScanOptions) -> DbIterator :abstractmethod: :async: Scans rows inside `range` using custom scan options. .. py:method:: shutdown() -> None :abstractmethod: :async: Closes the reader. .. py:method:: status() -> DbStatus :abstractmethod: Returns the latest reader status snapshot. .. py:method:: warm_sst(sst_id: SsTableId, targets: List[CacheTarget]) -> None :abstractmethod: :async: Warms selected cache content for one SST. Returns `Err` on the first failing target. If no block cache is configured, or if the SST is not reachable from the current manifest, the call is a no-op that returns `Ok(())`. .. py:class:: DbReaderBuilder(path: str, object_store: ObjectStore) Bases: :py:obj:`DbReaderBuilderProtocol` Builder for opening a read-only [`crate::DbReader`]. Builders are single-use: calling [`DbReaderBuilder::build`] consumes the builder. .. py:method:: build() -> DbReader :async: Opens the reader and consumes this builder. .. py:method:: with_checkpoint_id(checkpoint_id: str) -> None Pins the reader to an existing checkpoint UUID string. .. py:method:: with_filter_policies(policies: List[FilterPolicy]) -> None Sets the filter policies used when decoding SST filter blocks. Must match (or be a superset of) the writer's policies so SST filter sub-blocks can be decoded; unrecognized policy names are silently skipped. Defaults to a single bloom filter with 10 bits per key. .. py:method:: with_merge_operator(merge_operator: MergeOperator) -> None Installs an application-defined merge operator used while reading merge rows. .. py:method:: with_metrics_recorder(metrics_recorder: MetricsRecorder) -> None Installs an application-defined metrics recorder. .. py:method:: with_options(options: ReaderOptions) -> None Applies custom reader options. .. py:method:: with_wal_object_store(wal_object_store: ObjectStore) -> None Uses a separate object store for WAL files. .. py:class:: DbReaderBuilderProtocol Bases: :py:obj:`Protocol` Builder for opening a read-only [`crate::DbReader`]. Builders are single-use: calling [`DbReaderBuilder::build`] consumes the builder. .. py:method:: build() -> DbReader :abstractmethod: :async: Opens the reader and consumes this builder. .. py:method:: with_checkpoint_id(checkpoint_id: str) -> None :abstractmethod: Pins the reader to an existing checkpoint UUID string. .. py:method:: with_filter_policies(policies: List[FilterPolicy]) -> None :abstractmethod: Sets the filter policies used when decoding SST filter blocks. Must match (or be a superset of) the writer's policies so SST filter sub-blocks can be decoded; unrecognized policy names are silently skipped. Defaults to a single bloom filter with 10 bits per key. .. py:method:: with_merge_operator(merge_operator: MergeOperator) -> None :abstractmethod: Installs an application-defined merge operator used while reading merge rows. .. py:method:: with_metrics_recorder(metrics_recorder: MetricsRecorder) -> None :abstractmethod: Installs an application-defined metrics recorder. .. py:method:: with_options(options: ReaderOptions) -> None :abstractmethod: Applies custom reader options. .. py:method:: with_wal_object_store(wal_object_store: ObjectStore) -> None :abstractmethod: Uses a separate object store for WAL files. .. py:class:: DefaultMetricsRecorder Bases: :py:obj:`DefaultMetricsRecorderProtocol`, :py:obj:`MetricsRecorder` Built-in atomic-backed metrics recorder with snapshot access. .. py:method:: metric_by_name_and_labels(name: str, labels: List[MetricLabel]) -> Optional[Metric] Returns the metric matching `name` and the exact label set, if present. .. py:method:: metrics_by_name(name: str) -> List[Metric] Returns every metric with the requested name. .. py:method:: register_counter(name: str, description: Optional[str], labels: List[MetricLabel]) -> Counter Registers a monotonically increasing counter. .. py:method:: register_gauge(name: str, description: Optional[str], labels: List[MetricLabel]) -> Gauge Registers a gauge. .. py:method:: register_histogram(name: str, description: Optional[str], labels: List[MetricLabel], boundaries: List[float]) -> Histogram Registers a histogram with explicit bucket boundaries. .. py:method:: register_up_down_counter(name: str, description: Optional[str], labels: List[MetricLabel]) -> UpDownCounter Registers an up/down counter. .. py:method:: snapshot() -> List[Metric] Returns a point-in-time snapshot of every registered metric. .. py:class:: DefaultMetricsRecorderProtocol Bases: :py:obj:`Protocol` Built-in atomic-backed metrics recorder with snapshot access. .. py:method:: metric_by_name_and_labels(name: str, labels: List[MetricLabel]) -> Optional[Metric] :abstractmethod: Returns the metric matching `name` and the exact label set, if present. .. py:method:: metrics_by_name(name: str) -> List[Metric] :abstractmethod: Returns every metric with the requested name. .. py:method:: register_counter(name: str, description: Optional[str], labels: List[MetricLabel]) -> Counter :abstractmethod: .. py:method:: register_gauge(name: str, description: Optional[str], labels: List[MetricLabel]) -> Gauge :abstractmethod: .. py:method:: register_histogram(name: str, description: Optional[str], labels: List[MetricLabel], boundaries: List[float]) -> Histogram :abstractmethod: .. py:method:: register_up_down_counter(name: str, description: Optional[str], labels: List[MetricLabel]) -> UpDownCounter :abstractmethod: .. py:method:: snapshot() -> List[Metric] :abstractmethod: Returns a point-in-time snapshot of every registered metric. .. py:class:: LogCallbackImpl(*args, **kwargs) Bases: :py:obj:`LogCallback` Callback invoked for each emitted log record. .. py:method:: log(record: LogRecord) -> None Handles one log record. .. py:class:: LogCallback Callback invoked for each emitted log record. .. py:method:: log(record: LogRecord) -> None :abstractmethod: Handles one log record. .. py:class:: PrefixExtractorImpl(*args, **kwargs) Bases: :py:obj:`PrefixExtractor` Application-provided prefix extractor used to configure prefix-based bloom filters. .. py:method:: name() -> str Stable identifier for this extractor's configuration. Included in the bloom filter policy name so filters built with different extractors are never mismatched. .. py:method:: prefix_len(target: PrefixTarget) -> Optional[int] Returns the prefix length to use for `target`, or `None` when no prefix is extractable. .. py:class:: PrefixExtractor Application-provided prefix extractor used to configure prefix-based bloom filters. .. py:method:: name() -> str :abstractmethod: Stable identifier for this extractor's configuration. Included in the bloom filter policy name so filters built with different extractors are never mismatched. .. py:method:: prefix_len(target: PrefixTarget) -> Optional[int] :abstractmethod: Returns the prefix length to use for `target`, or `None` when no prefix is extractable. .. py:class:: WalFileIterator(*args, **kwargs) Bases: :py:obj:`WalFileIteratorProtocol` Iterator over raw row entries stored in a WAL file. .. py:method:: next() -> Optional[RowEntry] :async: Returns the next raw row entry from the WAL file. .. py:class:: WalFileIteratorProtocol Bases: :py:obj:`Protocol` Iterator over raw row entries stored in a WAL file. .. py:method:: next() -> Optional[RowEntry] :abstractmethod: :async: Returns the next raw row entry from the WAL file. .. py:class:: WalFile(*args, **kwargs) Bases: :py:obj:`WalFileProtocol` Handle for a single WAL file. .. py:method:: id() -> int Returns the WAL file ID. .. py:method:: iterator() -> WalFileIterator :async: Opens an iterator over raw row entries in this WAL file. .. py:method:: metadata() -> WalFileMetadata :async: Reads object-store metadata for this WAL file. .. py:method:: next_file() -> WalFile Returns a handle for the next WAL file ID without checking existence. .. py:method:: next_id() -> int Returns the WAL ID immediately after this file. .. py:class:: WalFileProtocol Bases: :py:obj:`Protocol` Handle for a single WAL file. .. py:method:: id() -> int :abstractmethod: Returns the WAL file ID. .. py:method:: iterator() -> WalFileIterator :abstractmethod: :async: Opens an iterator over raw row entries in this WAL file. .. py:method:: metadata() -> WalFileMetadata :abstractmethod: :async: Reads object-store metadata for this WAL file. .. py:method:: next_file() -> WalFile :abstractmethod: Returns a handle for the next WAL file ID without checking existence. .. py:method:: next_id() -> int :abstractmethod: Returns the WAL ID immediately after this file. .. py:class:: WalReader(path: str, object_store: ObjectStore) Bases: :py:obj:`WalReaderProtocol` Reader for WAL files stored under a database path. .. py:method:: get(id: int) -> WalFile Returns a handle for the WAL file with the given ID. .. py:method:: list(start_id: Optional[int], end_id: Optional[int]) -> List[WalFile] :async: Lists WAL files in ascending ID order. `start_id` is inclusive and `end_id` is exclusive when provided. .. py:class:: WalReaderProtocol Bases: :py:obj:`Protocol` Reader for WAL files stored under a database path. .. py:method:: get(id: int) -> WalFile :abstractmethod: Returns a handle for the WAL file with the given ID. .. py:method:: list(start_id: Optional[int], end_id: Optional[int]) -> List[WalFile] :abstractmethod: :async: Lists WAL files in ascending ID order. `start_id` is inclusive and `end_id` is exclusive when provided.