Querying

The SDK has no query builder of its own. You read local data in one of three ways: list and load items with Item.all and Item.find, run Drizzle queries against the SQLite database through BaseDb, or subscribe to a query with BaseDb.liveQuery. For published data in its canonical JSON form, use @seedprotocol/query.

import { BaseDb, seeds, metadata } from '@seedprotocol/sdk'

Choosing an approach

Item.all filters only by model, deleted state, whether to include on-chain items, and owned or watched addresses. For anything else, filter its results in your code, as Reading and writing data does, or query SQLite.

BaseDb.getAppDb

Returns the Drizzle database for the app's SQLite file.

static getAppDb(): any

Before client.init() has set up the platform, it throws Db not configured. Call BaseDb.configure() during platform init. Call it after client.init() has resolved. After client.stop() it returns undefined until the next init opens the database. The return type is any, so query results aren't typed.

Import Drizzle's operators (eq, and, sql and the rest) from @seedprotocol/sdk/drizzle. It re-exports the drizzle-orm build the SDK queries with, so you don't install Drizzle or match its version.

The file is <filesDir>/db/seed.db in both the browser and Node. Storage lists the engine each uses and the Node dbConfig.dbUrl override.

Tables

The main entry exports the Drizzle table objects. The two you'll query most:

seeds: one row per item.

metadata: one row per property value per version. Editing a property adds or updates a row on the item's current version, so a property can have several rows. An edit reaches this table only when its write applies, after the assignment returns, so await property.save() before you read metadata yourself.

New rows are stored under the property's storage name: the property's own name for most types (title), <name>Id for a single Relation, Image, File or Html property (authorId, bodyId), and a generated name for a list of relations, such as editorAuthorIds for editors, a list of Author. Rows written by an older SDK can hold the bare name (author, body). The SDK matches rows to their property by propertyId, so filter on it, or on every name the property's rows can have.

The other tables are versions, schemas, models, modelSchemas, properties, appState, modelUids, publishProcesses, uploadProcesses, easSyncProcesses, arweaveL1FinalizeJobs and htmlEmbeddedImageCoPublish. The database also has pending_writes (the outbox of edits waiting to be written) and entity_changes (the change feed's log), which aren't exported. All of them are the SDK's internal storage and can change between releases. Read them, but write through Item and ItemProperty.

Example: current titles of all posts

To find an item's current value, take its newest row per property. compareMetadataRowsLatestFirst sorts rows the same way the SDK does: newest first by attestation time, else creation time, with revoked rows counted like any other. On a published item, a revoked newest row with no value is a removed property, so an earlier version's value doesn't count.

import { BaseDb, compareMetadataRowsLatestFirst, metadata, seeds } from '@seedprotocol/sdk'
import { and, eq, isNull, or } from '@seedprotocol/sdk/drizzle'

const db = BaseDb.getAppDb()

const rows: Array<{
  seedLocalId: string
  title: string | null
  localId: string | null
  createdAt: number | null
  attestationCreatedAt: number | null
  revokedAt: number | null
}> = await db
  .select({
    seedLocalId: metadata.seedLocalId,
    title: metadata.propertyValue,
    localId: metadata.localId,
    createdAt: metadata.createdAt,
    attestationCreatedAt: metadata.attestationCreatedAt,
    revokedAt: metadata.revokedAt,
  })
  .from(metadata)
  .innerJoin(seeds, eq(seeds.localId, metadata.seedLocalId))
  .where(
    and(
      eq(seeds.type, 'post'),
      eq(metadata.propertyName, 'title'),
      or(isNull(seeds._markedForDeletion), eq(seeds._markedForDeletion, 0)),
    ),
  )

const titles = new Map<string, (typeof rows)[number]>()
for (const row of rows) {
  const current = titles.get(row.seedLocalId)
  if (!current || compareMetadataRowsLatestFirst(row, current) < 0) {
    titles.set(row.seedLocalId, row)
  }
}

pickLatestMetadataRowPerProperty(rows) does the same for the rows of one item, keeping one row per property: rows group by propertyId, and a row without one joins the rows stored under its name.

BaseDb.liveQuery

Runs a query and emits its results again whenever they change.

static liveQuery<T>(query: ((sql: any) => any) | any): Observable<T[]>

Parameters

Returns

An RxJS Observable of result rows. It emits once with the current results, then again each time they change. Rows are compared as JSON, so an unchanged result isn't emitted twice. Call unsubscribe() on the subscription to stop.

A query that fails sends the error to the subscriber. In the browser the SDK also logs it under the seedSdk:browser:db:Db debug namespace, not to the console.

Example

import { BaseDb, seeds } from '@seedprotocol/sdk'
import { eq } from '@seedprotocol/sdk/drizzle'

const db = BaseDb.getAppDb()

const subscription = BaseDb.liveQuery<{ id: string }>(
  db.select({ id: seeds.localId }).from(seeds).where(eq(seeds.type, 'post')),
).subscribe((rows) => {
  console.log(`${rows.length} posts`)
})

// later
subscription.unsubscribe()

Browser and Node

In the browser, calls with the same SQL tag query and parameters return the same observable while it has subscribers, so they share one SQLocal query, and a late subscriber gets the last rows at once. Each Drizzle query builder gets its own.

Use Drizzle queries if your code runs in both environments. On Node the poll runs on a timer that keeps the process alive while a subscription is open. client.stop() (or BaseDb.close()) completes every open subscription, which ends its timer.

In React, useLiveQuery from @seedprotocol/react wraps liveQuery and handles subscribing and cleanup. See Live queries and Querying with liveQuery.

BaseDb.transaction

Runs fn in one transaction and resolves with its result.

static transaction<T>(fn: (tx: any) => Promise<T>): Promise<T>

tx is a Drizzle database, used like getAppDb(). Every query fn runs on tx commits together, or none does when fn throws, and the transaction rejects with what fn threw. When another tab holds the database lock (SQLITE_BUSY), the whole transaction runs again, up to five more times over about a second. So:

• fn must have no side effects outside tx.
• Don't call BaseDb.getAppDb() or BaseDb.transaction inside fn. Queries on the app database wait for the open transaction to end, so fn would wait for itself.

On Node the SDK keeps one connection and runs one transaction at a time; other statements wait for it.

import { BaseDb, metadata, seeds } from '@seedprotocol/sdk'

const counts = await BaseDb.transaction(async (tx) => ({
  items: (await tx.select().from(seeds)).length,
  values: (await tx.select().from(metadata)).length,
}))

Other BaseDb methods

Other read helpers

These functions read SQLite, and file sizes where noted, and change nothing:

Each takes an item or { seedLocalId, seedUid } unless shown otherwise. markPropertyAttestationsRetracted({ uids, revokedAt }) is the one write in this group: @seedprotocol/publish calls it after revoking a retracted property's attestations, and it marks their rows revoked and empties them. The main entry also exports lower-level readers used by @seedprotocol/react and @seedprotocol/publish, such as getMetadataLatest and getVersionData. They return Drizzle subqueries and aren't covered here.

Change feed

In the browser, every write to seeds, versions and metadata is logged in entity_changes, and each tab reads new log rows when they appear, including rows another tab wrote. Loaded items and properties use it to re-read only their own rows; Reactivity model explains how. The feed's functions are exported for code that keeps its own copy of an item's rows. On Node there's no feed: isChangeFeedRunning() returns false and listeners are never called. Writes are still logged in entity_changes there, and the SDK deletes rows older than 10 minutes when it opens the database and every minute after.

type EntityChangeTable = 'seeds' | 'versions' | 'metadata'

type ChangeWatch = {
  seedLocalId?: string | null
  seedUid?: string | null
  tables: EntityChangeTable[]
  propertyNames?: string[]
}

function watchEntityChanges(watch: ChangeWatch, listener: () => void): () => void

function watchEntityRows<T>(
  watch: ChangeWatch,
  read: () => Promise<T>,
  onRows: (rows: T) => void,
  options?: { immediate?: boolean; onError?: (error: unknown) => void },
): { unsubscribe: () => void }

function isChangeFeedRunning(): boolean

watchEntityChanges calls listener after a committed write to one of watch.tables for the watched item, matched by seedLocalId or by seedUid (ignoring case). With propertyNames, only metadata rows of those storage names count. Several matching writes found in one read of the log call it once. It returns a function that stops the watch.

watchEntityRows runs read each time the watch fires and passes the result to onRows when it differs, as JSON, from the last result passed. A read that finishes after a newer one started is dropped. immediate: true also runs read once right away. A failed read goes to onError, or to the debug log without one.

import { BaseDb, metadata, watchEntityRows } from '@seedprotocol/sdk'
import { eq } from '@seedprotocol/sdk/drizzle'

const db = BaseDb.getAppDb()

const watch = watchEntityRows(
  { seedLocalId: post.seedLocalId, tables: ['metadata'] },
  () => db.select().from(metadata).where(eq(metadata.seedLocalId, post.seedLocalId)),
  (rows) => updateSearchIndex(post.seedLocalId, rows),
  { immediate: true },
)

// later
watch.unsubscribe()

The leader tab deletes log rows older than 10 minutes. A tab that falls further behind than that calls every listener once.

Published data

Item and liveQuery read your local drafts and local copies. To read published records as JSON, with relations and file content resolved, use @seedprotocol/query. client.init() registers the SDK's database as its local source, so its queries can answer from local data first.

The SDK exports one shortcut:

function getPublishedSeedRecord(
  seedUid: string,
  options?: GetPublishedSeedRecordOptions,
): Promise<GetSeedResult | null>

It calls getSeed from @seedprotocol/query. options.source defaults to 'local', which reads only the local database. Pass 'auto' to fall back to remote sources. It returns null when no record is found. The other options are getSeed's, documented in @seedprotocol/query.

import { getPublishedSeedRecord } from '@seedprotocol/sdk'

const record = await getPublishedSeedRecord(post.seedUid!, { source: 'auto' })

registerSeedQueryLocalSource(), unregisterSeedQueryLocalSource(), isSeedQueryLocalSourceRegistered() and createLocalQueryDataSource() manage that registration. client.stop() and client.unload() unregister the source, and getPublishedSeedRecord registers it again when it isn't registered and the database is ready. See Reading published data.

Related

• Item: Item.all and Item.find in full
• Reactivity model: how the change feed keeps loaded items current
• Querying with liveQuery
• React live queries: useLiveQuery
• @seedprotocol/query and its adapters
• Reading and writing data