SimpleQuery class

The main entry point for querying and modifying device data.

Singleton. Always use SimpleQuery.instance; never call the private constructor. Tests that want to swap the underlying backend don't replace SimpleQuery.instance — they assign to SimpleQueryPlatform.instance instead (the facade delegates every call through it).

Example:

final contacts = await SimpleQuery.instance.queryTyped(
  const QueryRequest(domain: QueryDomain.contacts),
  ContactRecord.fromRecord,
);

See docs/DESIGN.md for the principles behind the API shape.

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

batch(BatchRequest request) → Future<BatchResult>
Executes a sequence of mutations. sequentialBestEffort semantics: a failed operation records its error in its own MutationResult.metadata error key and does not abort the batch. Android may execute atomically when the underlying provider supports it; see docs/API_SEMANTICS.md.
callExtension({required String namespace, required String method, Map<String, Object?>? args}) → Future<Map<String, Object?>?>
Calls a platform-specific extension method.
closeBinary(String handleId) → Future<void>
Closes a binary handle by id. Pair with openBinary. Most callers should prefer openBinaryContent / withBinaryContent which manage the handle automatically.
dispose() → Future<void>
Releases platform resources (observers, open binary handles, etc.). Typically called once at app shutdown. Idempotent.
getCapabilities() → Future<CapabilitySnapshot>
Reports, for every QueryDomain, which operations (read / write / observe / stream) are usable on this device right now. Always check before issuing a request — the defaults on unsupported platforms report everything as false.
mutate(MutationRequest request) → Future<MutationResult>
Executes a single insert / update / delete. For multi-operation atomic-where-possible writes use batch. Throws SimpleQueryError on failure.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
observe(ObserveRequest request) → Stream<ObserveEvent>
Watches ObserveRequest.domain for changes. Emits ObserveEvents until the subscription is cancelled. Non-Android platforms use polling fallback when native change notifications aren't available — rate controlled by ObserveRequest.pollingInterval.
openBinary(BinaryRequest request) → Future<BinaryContentHandle>
Opens binary content (e.g. a photo body) and returns the wire-format handle. Most callers should prefer openBinaryContent or withBinaryContent which wrap the handle with a safe close() instead of forcing the caller to track a bare handleId.
openBinaryContent(BinaryRequest request) → Future<BinaryContent>
Opens binary content as a self-closing BinaryContent. Caller is responsible for calling close() on the returned object — or use withBinaryContent for a scoped helper that closes on return.
query(QueryRequest request) → Future<QueryResult>
Runs request against the current platform backend. Prefer queryTyped, queryBuilder, or queryPaginated when you want typed records, fluent construction, or exhaustive pagination.
queryBuilder(QueryDomain domain) → QueryBuilder
Returns a fluent QueryBuilder scoped to domain. Sugar over QueryBuilder(domain) — useful for chaining off SimpleQuery.instance.
queryPaginated(QueryRequest request) → Stream<QueryResult>
Walks every page of request to exhaustion, emitting one QueryResult per page.
queryPaginatedTyped<T>(QueryRequest request, T fromRecord(Map<String, Object?> record)) → Stream<List<T>>
Same shape as queryPaginated but maps each record through fromRecord before yielding. The stream emits one batch (a List<T>) per page.
queryRaw({required String contentUri, List<QueryFilterCondition> filters = const <QueryFilterCondition>[], List<String>? projection, List<QuerySort> sort = const <QuerySort>[], QueryPage? page, Map<String, Object?>? platformData}) → Future<QueryResult>
Query an arbitrary content provider by URI, bypassing the canonical schema.
queryTyped<T>(QueryRequest request, T fromRecord(Map<String, Object?>)) → Future<List<T>>
Runs request and maps each returned record through fromRecord.
toString() → String
A string representation of this object.
inherited
withBinaryContent<R>(BinaryRequest request, Future<R> body(BinaryContent content)) → Future<R>
Opens binary content for the duration of body, guaranteeing it is closed when body returns or throws. Returns whatever body returns.

Operators

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

Static Properties

instance → SimpleQuery
The singleton. Safe to cache; identity is stable for the life of the isolate.
final