ApiFull

ApiFull<TResult, TTableDef, TWithout> = object

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:167

Type Parameters

TResult

TResult

TTableDef

TTableDef extends TableDefBase

TWithout

TWithout extends ApiFeature

Properties

count()

readonly count: () => QueryBuilder<number, TTableDef, TWithout | "row" | "count" | "select" | "orderBy" | "first" | "offset" | "limit" | "returning" | "onConflict">

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:213

Example:

db.todos.count()
db.todos.count().where('completed', true)

Returns

delete()

readonly delete: () => QueryBuilder<TResult, TTableDef, TWithout | "row" | "select" | "count" | "orderBy" | "first" | "offset" | "limit" | "onConflict">

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:323

Delete rows from the table that match the where clause

Example:

db.todos.delete().where({ status: 'completed' })

Note that it’s generally recommended to do soft-deletes for synced apps.

Returns

first()

readonly first: <TBehaviour, TFallback>(behaviour?) => QueryBuilder<TBehaviour extends object ? ReturnType<TBehaviour["fallback"]> | GetSingle<TResult> : TBehaviour extends object ? undefined | GetSingle<TResult> : GetSingle<TResult>, TTableDef, TWithout | "row" | "first" | "orderBy" | "select" | "limit" | "offset" | "where" | "returning" | "onConflict">

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:253

Example:

db.todos.first()
db.todos.where('id', '123').first() // will return `undefined` if no rows are returned
db.todos.where('id', '123').first({ behaviour: 'error' }) // will throw if no rows are returned
db.todos.first({ behaviour: 'fallback', fallback: () => ({ id: '123', text: 'Buy milk', status: 'active' }) })

Behaviour:

undefined: Will return undefined if no rows are returned (default behaviour)
error: Will throw if no rows are returned
fallback: Will return a fallback value if no rows are returned

Type Parameters

TBehaviour

TBehaviour extends FirstQueryBehaviour<GetSingle<TResult>, TFallback>

TFallback

TFallback = never

Parameters

behaviour?

FirstQueryBehaviour<GetSingle<TResult>, TFallback> & TBehaviour

Returns

insert()

readonly insert: (values) => QueryBuilder<TResult, TTableDef, TWithout | "row" | "select" | "count" | "orderBy" | "first" | "offset" | "limit" | "where">

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:266

Insert a new row into the table

Example:

db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' })

Parameters

values

TTableDef["insertSchema"]["Type"]

Returns

limit()

readonly limit: (limit) => QueryBuilder<TResult, TTableDef, TWithout | "row" | "limit" | "offset" | "first" | "orderBy" | "returning" | "onConflict">

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:238

Example:

db.todos.limit(10)

Parameters

limit

number

Returns

offset()

readonly offset: (offset) => QueryBuilder<TResult, TTableDef, TWithout | "row" | "offset" | "orderBy" | "returning" | "onConflict">

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:231

Example:

db.todos.offset(10)

Parameters

offset

number

Returns

onConflict()

readonly onConflict: {<TTarget>(target, action): QueryBuilder<TResult, TTableDef, TWithout | "select" | "where" | "count" | "orderBy" | "offset" | "limit" | "first" | "row">; <TTarget>(target, action, updateValues): QueryBuilder<TResult, TTableDef, TWithout | "select" | "where" | "count" | "orderBy" | "offset" | "limit" | "first" | "row">; }

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:289

Upsert: insert a row, or handle conflicts on existing rows. Equivalent to SQLite’s INSERT ... ON CONFLICT clause.

Actions:

'ignore': Skip the insert if a row with the same key exists
'replace': Delete the existing row and insert the new one
'update': Update specific columns on the existing row

// Ignore: skip if row exists
db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'ignore')

// Replace: delete existing row and insert new one
db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'replace')

// Update: merge specific columns into existing row
db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'update', { text: 'Buy soy milk' })

NOTE: Composite primary keys are not yet supported.

Call Signature

<TTarget>(target, action): QueryBuilder<TResult, TTableDef, TWithout | "select" | "where" | "count" | "orderBy" | "offset" | "limit" | "first" | "row">

Type Parameters

TTarget

TTarget extends string | number | symbol | readonly keyof TTableDef["sqliteDef"]["columns"][]

Parameters

target

TTarget

action

"replace" | "ignore"

Returns

Call Signature

<TTarget>(target, action, updateValues): QueryBuilder<TResult, TTableDef, TWithout | "select" | "where" | "count" | "orderBy" | "offset" | "limit" | "first" | "row">

Type Parameters

TTarget

TTarget extends string | number | symbol | readonly keyof TTableDef["sqliteDef"]["columns"][]

Parameters

target

TTarget

action

"update"

updateValues

Partial<TTableDef["rowSchema"]["Type"]>

Returns

orderBy()

readonly orderBy: {<TColName>(col, direction): QueryBuilder<TResult, TTableDef, TWithout | "onConflict" | "returning">; <TParams>(params): QueryBuilder<TResult, TTableDef, TWithout | "onConflict" | "returning">; }

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:221

Example:

db.todos.orderBy('createdAt', 'desc')
db.todos.orderBy([{ col: 'createdAt', direction: 'desc' }])

Call Signature

<TColName>(col, direction): QueryBuilder<TResult, TTableDef, TWithout | "onConflict" | "returning">

Type Parameters

TColName

TColName extends string

Parameters

col

TColName

direction

"asc" | "desc"

Returns

QueryBuilder<TResult, TTableDef, TWithout | "onConflict" | "returning">

Call Signature

<TParams>(params): QueryBuilder<TResult, TTableDef, TWithout | "onConflict" | "returning">

Type Parameters

TParams

TParams extends OrderByParams<TTableDef>

Parameters

params

TParams

Returns

QueryBuilder<TResult, TTableDef, TWithout | "onConflict" | "returning">

returning()

readonly returning: <TColumns>(…columns) => QueryBuilder<ReadonlyArray<{ readonly [K in TColumns]: TTableDef["sqliteDef"]["columns"][K]["schema"]["Type"] }>, TTableDef>

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:301

Similar to the .select API but for write queries (insert, update, delete).

Example:

db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).returning('id')

Type Parameters

TColumns

TColumns extends keyof TTableDef["sqliteDef"]["columns"] & string

Parameters

columns

…TColumns[]

Returns

QueryBuilder<ReadonlyArray<{ readonly [K in TColumns]: TTableDef["sqliteDef"]["columns"][K]["schema"]["Type"] }>, TTableDef>

select()

readonly select: {<TColumn>(pluckColumn): QueryBuilder<readonly TTableDef["sqliteDef"]["columns"][TColumn]["schema"]["Type"][], TTableDef, TWithout | "select" | "onConflict" | "returning" | "row">; <TColumns>(…columns): QueryBuilder<readonly { readonly [K in string]: TTableDef["sqliteDef"]["columns"][K]["schema"]["Type"] }[], TTableDef, TWithout | "select" | "count" | "onConflict" | "returning" | "row">; }

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:177

SELECT * is the default

Example:

db.todos.select('id', 'text', 'completed')
db.todos.select('id')

Call Signature

<TColumn>(pluckColumn): QueryBuilder<readonly TTableDef["sqliteDef"]["columns"][TColumn]["schema"]["Type"][], TTableDef, TWithout | "select" | "onConflict" | "returning" | "row">

Selects and plucks a single column

Type Parameters

TColumn

TColumn extends string

Parameters

pluckColumn

TColumn

Returns

QueryBuilder<readonly TTableDef["sqliteDef"]["columns"][TColumn]["schema"]["Type"][], TTableDef, TWithout | "select" | "onConflict" | "returning" | "row">

Call Signature

<TColumns>(…columns): QueryBuilder<readonly { readonly [K in string]: TTableDef["sqliteDef"]["columns"][K]["schema"]["Type"] }[], TTableDef, TWithout | "select" | "count" | "onConflict" | "returning" | "row">

Select multiple columns

Type Parameters

TColumns

TColumns extends string

Parameters

columns

…TColumns[]

Returns

QueryBuilder<readonly { readonly [K in string]: TTableDef["sqliteDef"]["columns"][K]["schema"]["Type"] }[], TTableDef, TWithout | "select" | "count" | "onConflict" | "returning" | "row">

update()

readonly update: (values) => QueryBuilder<TResult, TTableDef, TWithout | "row" | "select" | "count" | "orderBy" | "first" | "offset" | "limit" | "onConflict">

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:312

Update rows in the table that match the where clause

Example:

db.todos.update({ status: 'completed' }).where({ id: '123' })

Parameters

values

Partial<TTableDef["rowSchema"]["Type"]>

Returns

where()

readonly where: {(params): QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">; <TColName>(col, value): QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">; <TColName>(col, op, value): QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">; <TColName>(col, op, value): QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">; }

Defined in: packages/@livestore/common/dist/schema/state/sqlite/query-builder/api.d.ts:200

Notes:

All where clauses are ANDed together by default.
null values only support = and != which is translated to IS NULL and IS NOT NULL.

Example:

db.todos.where('completed', true)
db.todos.where('completed', '!=', true)
db.todos.where({ completed: true })
db.todos.where({ completed: { op: '!=', value: true } })

TODO: Also support OR

Call Signature

(params): QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">

Parameters

params

WhereParams<TTableDef>

Returns

QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">

Call Signature

<TColName>(col, value): QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">

Type Parameters

TColName

TColName extends string | number | symbol

Parameters

col

TColName

value

TTableDef["sqliteDef"]["columns"][TColName]["schema"]["Type"]

Returns

QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">

Call Signature

<TColName>(col, op, value): QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">

Type Parameters

TColName

TColName extends string | number | symbol

Parameters

col

TColName

op

In

value

readonly TTableDef["sqliteDef"]["columns"][TColName]["schema"]["Type"][]

Returns

QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">

Call Signature

<TColName>(col, op, value): QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">

Type Parameters

TColName

TColName extends string | number | symbol

Parameters

col

TColName

op

SingleValue

value

TTableDef["sqliteDef"]["columns"][TColName]["schema"]["Type"]

Returns

QueryBuilder<TResult, TTableDef, TWithout | "select" | "row">