PagedTable class - paged_table library

Properties

basePath → String: Common base path; the table owns <base>.heap, <base>.idx, and <base>.meta.json.
final
columnNames → List<String>: Column names in declaration order.
no setteroverride
columns → List<PagedColumn>: final
hashCode → int: The hash code for this object.
no setterinherited
kind → TableBackendKind: Which storage engine backs this table.
no setteroverride
length → int: Number of rows currently in the table.
no setter
pageSize → int: Bytes per page used by this table's heap + index files. Set at create time, persisted in meta.json, and authoritative on reopen (the on-disk value overrides any caller-supplied default).
no setter
primaryKey → PagedColumn: no setter
primaryKeyIndex → int: Index of the primary-key column in columns.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
secondaryIndexNames → List<String>: Names of every secondary index on this table. Order is the order they were registered.
no setter
tableName ↔ String: User-visible table name as known to the SQL layer.
getter/setter pairoverride-getter

Methods

close() → Future<void>: Close both backing files. Implicitly commits.
commit() → Future<void>: Commit pending mutations on both files.
createIndex(String name, List<String> columnNames, {bool unique = false}) → Future<void>: Build a new secondary index name over column columnName. Walks every existing row, populates the index, commits everything, and rewrites meta.json so the index survives reopen. Throws when name is already taken or columnName is unknown.
delete(Object pkVal) → Future<bool>: Delete the row with primary key pkVal. Returns true if it existed.
dropIndex(String name) → Future<bool>: Drop secondary index name. Removes the on-disk files and rewrites meta.json. Idempotent — returns false if the index didn't exist.
findConflictByUniqueIndex(String indexName, Map<String, Object?> row) → Future<Object?>: Look up the (single) row that conflicts with row on the UNIQUE secondary index named indexName. Returns the existing row's PK value, or null when there is no conflict (including when any indexed component of row is NULL).
findUniqueIndexByColumns(List<String> columnNames) → String?: If a UNIQUE secondary index exists whose column list is exactly columnNames (case-insensitive, order-sensitive), return its name. Used by INSERT … ON CONFLICT (cols) to resolve the conflict target to a unique constraint.
get(Object pkVal) → Future<Map<String, Object?>?>: Look up a row by primary key. Returns null if absent.
indexColumn(String indexName) → String?: First (leading) column name of secondary index indexName, or null when there is no such index. Kept for the single-column callers that pre-date composite indexes; prefer indexColumns.
indexColumns(String indexName) → List<String>?: All indexed column names (in order) for secondary index indexName, or null when there is no such index.
indexLookup(String indexName, List<Object?> values) → Stream<Map<String, Object?>>: Stream every row that matches the leading prefix [values] of the indexed columns. For a single-column index, values has one entry — this is point equality. For a composite index, you may supply fewer values than the index has columns to do a prefix probe (e.g. [country] against an (country, city) index).
indexRange(String indexName, {List<Object?> equalPrefix = const [], Object? lower, bool lowerInclusive = true, Object? upper, bool upperInclusive = false}) → Stream<Map<String, Object?>>: Range-scan a secondary index. equalPrefix (optional) pins leading columns by equality; lower / upper then apply to the next column after that prefix. For a single-column index, pass an empty equalPrefix and bounds on the only column. The encoded value-keys are byte-order-preserving, so SQL semantics carry through.
insert(Map<String, Object?> row) → Future<void>: Insert a row. The map's keys must be a subset of the column names; missing columns are stored as NULL. Throws if a row with the same PK already exists.
insertOrIgnore(Map<String, Object?> row) → Future<bool>: SQLite INSERT OR IGNORE: if the row would conflict with the PK or any UNIQUE secondary index, skip the insert and return false. Returns true if the row was inserted.
insertOrReplace(Map<String, Object?> row) → Future<int>: SQLite INSERT OR REPLACE: delete every existing row that would conflict (PK match or any UNIQUE-index match), then insert the new row. Returns the number of rows deleted in service of the insert (0 when no conflict existed).
isIndexUnique(String indexName) → bool: True iff the secondary index indexName was declared UNIQUE. Returns false for non-unique indexes and for unknown names.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
range({Object? lower, bool lowerInclusive = true, Object? upper, bool upperInclusive = false}) → Stream<Map<String, Object?>>: Stream every row whose PK falls in [lower?, upper?).
reassignPrimaryKey(Object oldPkVal, Map<String, Object?> row) → Future<void>: Replace the row at primary key oldPkVal with row, possibly rewriting the primary key. The new PK value (read from row[primaryKey.name]) must not already belong to a different row; UNIQUE secondary indexes are checked against the new row before any mutation, so a conflict leaves the table untouched. Equivalent to delete + insert but atomic w.r.t. uniqueness probing.
rollback() → Future<void>: Discard pending mutations on every backing file (heap, primary B+-tree, and any open secondary indexes). After this call the table reflects the on-disk state as of the last commit.
scan() → Stream<Map<String, Object?>>: Stream every row in primary-key order. One heap page resident at a time.
toString() → String: A string representation of this object.
inherited
update(Object pkVal, Map<String, Object?> row) → Future<void>: Replace an existing row. Throws if the PK doesn't exist. The primary-key value in row must equal pkVal (we don't allow PK rewrites here — do delete + insert if you need that).

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

create(String basePath, {required List<PagedColumn> columns, required String primaryKey, int pageSize = 4096, int cacheCapacity = 64}) → Future<PagedTable>: Create a brand-new paged table. Refuses to overwrite an existing <basePath>.meta.json.
open(String basePath, {int pageSize = 4096, int cacheCapacity = 64}) → Future<PagedTable>: Open an existing paged table from <basePath>.meta.json. Throws if the metadata file does not exist. When the metadata records a pageSize, it overrides the pageSize argument (the on-disk page size is authoritative — changing it after the table exists would corrupt every page boundary).
openOrCreate(String basePath, {required List<PagedColumn> columns, required String primaryKey, int pageSize = 4096, int cacheCapacity = 64}) → Future<PagedTable>: Open an existing table or create one if <basePath>.meta.json is missing. The schema is only consulted when creating.