Skip to content
LiveStore Logo LiveStore (0.3.0-dev.33)

ApiFull

ApiFull<TResult, TTableDef, TWithout>: object

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

Type Parameters

• TResult

• TTableDef extends TableDefBase

• TWithout extends ApiFeature

Type declaration

count()

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

Example:

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

Returns

QueryBuilder<number, TTableDef, TWithout | "row" | "count" | "select" | "orderBy" | "first" | "offset" | "limit" | "returning" | "onConflict">

delete()

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

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

QueryBuilder<TResult, TTableDef, TWithout | "row" | "select" | "count" | "orderBy" | "first" | "offset" | "limit" | "onConflict">

first()

readonly first: <TFallback>(options?) => QueryBuilder<TFallback | GetSingle<TResult>, TTableDef, TWithout | "row" | "first" | "orderBy" | "select" | "limit" | "offset" | "where" | "returning" | "onConflict">

Example:

db.todos.first()
db.todos.where('id', '123').first()

Query will fail if no rows are returned and no fallback is provided.

Type Parameters

• TFallback = never

Parameters

options?
fallback?

() => TFallback | GetSingle<TResult>

Returns

QueryBuilder<TFallback | GetSingle<TResult>, TTableDef, TWithout | "row" | "first" | "orderBy" | "select" | "limit" | "offset" | "where" | "returning" | "onConflict">

insert()

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

Insert a new row into the table

Example:

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

Parameters

values

TTableDef["insertSchema"]["Type"]

Returns

QueryBuilder<TResult, TTableDef, TWithout | "row" | "select" | "count" | "orderBy" | "first" | "offset" | "limit" | "where">

limit()

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

Example:

db.todos.limit(10)

Parameters

limit

number

Returns

QueryBuilder<TResult, TTableDef, TWithout | "row" | "limit" | "offset" | "first" | "orderBy" | "returning" | "onConflict">

offset()

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

Example:

db.todos.offset(10)

Parameters

offset

number

Returns

QueryBuilder<TResult, TTableDef, TWithout | "row" | "offset" | "orderBy" | "returning" | "onConflict">

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">

Example: If the row already exists, it will be ignored.

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

Example: If the row already exists, it will be replaced.

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

Example: If the row already exists, it will be updated.

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

NOTE This API doesn’t yet support composite primary keys.

Type Parameters

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

Parameters

target

TTarget

action

"ignore" | "replace"

Returns

QueryBuilder<TResult, TTableDef, TWithout | "select" | "where" | "count" | "orderBy" | "offset" | "limit" | "first" | "row">

Type Parameters

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

Parameters

target

TTarget

action

"update"

updateValues

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

Returns

QueryBuilder<TResult, TTableDef, TWithout | "select" | "where" | "count" | "orderBy" | "offset" | "limit" | "first" | "row">

orderBy()

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

Example:

db.todos.orderBy('createdAt', 'desc')

Type Parameters

• TColName extends string

Parameters

col

TColName

direction

"asc" | "desc"

Returns

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

Type Parameters

• 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>

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 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">

SELECT * is the default

Example:

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

Selects and plucks a single column

Type Parameters

• TColumn extends string

Parameters

pluckColumn

TColumn

Returns

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

Select multiple columns

Type Parameters

• 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">

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

QueryBuilder<TResult, TTableDef, TWithout | "row" | "select" | "count" | "orderBy" | "first" | "offset" | "limit" | "onConflict">

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">

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

Parameters

params

Partial<{ [K in string | number | symbol]: undefined | TTableDef[“sqliteDef”][“columns”][K][“schema”][“Type”] | { op: SingleValue; value: (…)[(…)][“columns”][K][“schema”][“Type”] } | { op: MultiValue; value: ReadonlyArray<(…)[(…)][K][“schema”][“Type”]> } }>

Returns

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

Type Parameters

• TColName extends string | number | symbol

Parameters

col

TColName

value

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

Returns

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

Type Parameters

• TColName extends string | number | symbol

Parameters

col

TColName

op

WhereOps

value

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

Returns

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