Interface IStructuredStore

Application port for a structured (row/collection-oriented) persistence backend: tables of StructuredRecords addressed by StoreTable, queried and mutated through backend-agnostic filters, ordering, and trimming.

Namespace: Serenity.Persistence.Domain.Interfaces

Assembly: Serenity.Global.Domain.dll

Syntax

public interface IStructuredStore

Remarks

Implementations decide how and where records are stored (an in-memory fake, a sharded key-value store, a remote HTTP service, a relational database, a document database). Callers depend on this abstraction, never on a concrete backend.

Callers OWN schema/kind consistency: every record written to a table must use one consistent StructuredValueKind per field (matching the declared StructuredTableSchema where one exists) — stores never coerce mismatched kinds, and a mismatch surfaces as a PersistenceStoreException from the backend (or an ArgumentException from the in-memory comparison) rather than silently converting.

Properties

Namespace

A diagnostic identifier for this store instance (e.g. its backing namespace or base URL).

Declaration

string Namespace { get; }

Property Value

Type	Description
string

Methods

CountAsync(StoreTable, IReadOnlyList<FieldFilter>, IReadOnlyList<string>, CancellationToken)

Counts the records matching filters, collapsed to one per distinctBy group when non-empty.

Declaration

Task<long> CountAsync(StoreTable table, IReadOnlyList<FieldFilter> filters, IReadOnlyList<string> distinctBy, CancellationToken cancellationToken)

Parameters

Type	Name	Description
StoreTable	table
IReadOnlyList<FieldFilter>	filters
IReadOnlyList<string>	distinctBy
CancellationToken	cancellationToken

Returns

Type	Description
Task<long>

DeleteByQueryAsync(StoreTable, IReadOnlyList<FieldFilter>, CancellationToken)

Deletes every record matching filters.

Declaration

Task DeleteByQueryAsync(StoreTable table, IReadOnlyList<FieldFilter> filters, CancellationToken cancellationToken)

Parameters

Type	Name	Description
StoreTable	table
IReadOnlyList<FieldFilter>	filters
CancellationToken	cancellationToken

Returns

Type	Description
Task

EnsureSchemaAsync(StructuredTableSchema, CancellationToken)

Creates or updates schema's table/collection and indexes, when the backend supports schema management.

Declaration

Task EnsureSchemaAsync(StructuredTableSchema schema, CancellationToken cancellationToken)

Parameters

Type	Name	Description
StructuredTableSchema	schema
CancellationToken	cancellationToken

Returns

Type	Description
Task

HealthCheckAsync(CancellationToken)

Checks whether the backing store is reachable and healthy. Never throws.

Declaration

Task<bool> HealthCheckAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<bool>

InsertAsync(StoreTable, StructuredRecord, StructuredTrim, CancellationToken)

Inserts record as a new row, optionally trimming the table down to trim's KeepCount afterward.

Declaration

Task InsertAsync(StoreTable table, StructuredRecord record, StructuredTrim trim, CancellationToken cancellationToken)

Parameters

Type	Name	Description
StoreTable	table
StructuredRecord	record
StructuredTrim	trim
CancellationToken	cancellationToken

Returns

Type	Description
Task

QueryAsync(StoreTable, StructuredQuery, CancellationToken)

Runs query against table.

Declaration

Task<IReadOnlyList<StructuredRecord>> QueryAsync(StoreTable table, StructuredQuery query, CancellationToken cancellationToken)

Parameters

Type	Name	Description
StoreTable	table
StructuredQuery	query
CancellationToken	cancellationToken

Returns

Type	Description
Task<IReadOnlyList<StructuredRecord>>

TrimBeyondAsync(StoreTable, IReadOnlyList<FieldFilter>, IReadOnlyList<OrderField>, int, CancellationToken)

Within the records matching scopeFilters, keeps only the best keepCount — in ordering order — deleting the rest. Records outside the scope are never touched.

Declaration

Task TrimBeyondAsync(StoreTable table, IReadOnlyList<FieldFilter> scopeFilters, IReadOnlyList<OrderField> ordering, int keepCount, CancellationToken cancellationToken)

Parameters

Type	Name	Description
StoreTable	table
IReadOnlyList<FieldFilter>	scopeFilters
IReadOnlyList<OrderField>	ordering
int	keepCount
CancellationToken	cancellationToken

Returns

Type	Description
Task

UpsertIfBetterAsync(StoreTable, StructuredRecord, IReadOnlyList<string>, string, StructuredSortDirection, StructuredTrim, CancellationToken)

Atomically, per keyFields: if no existing record matches, inserts record; otherwise replaces ALL of the existing record's fields with record's fields if and only if record's comparisonField value is STRICTLY better (per betterDirection) than the existing record's — an equal value is NOT better and the existing record is kept unchanged. Optionally trims afterward.

Declaration

Task UpsertIfBetterAsync(StoreTable table, StructuredRecord record, IReadOnlyList<string> keyFields, string comparisonField, StructuredSortDirection betterDirection, StructuredTrim trim, CancellationToken cancellationToken)

Parameters

Type	Name	Description
StoreTable	table
StructuredRecord	record
IReadOnlyList<string>	keyFields
string	comparisonField
StructuredSortDirection	betterDirection
StructuredTrim	trim
CancellationToken	cancellationToken

Returns

Type	Description
Task