# Query builder

All query methods and result cardinality.

[Read the read and write guide](/docs/crud/). Signatures below come from the published SDK declarations. Access SDK services through `db`; use their constructors only when integrating at a lower level.

## SelectOptions


```ts
interface SelectOptions {
  count?: "exact";
  head?: boolean;
}
```

## QueryBuilder


```ts
/** Queries are immutable and execute once when awaited. */
declare class QueryBuilder<
  T extends object,
  Selected = Row<T>,
  C extends Cardinality = "many",
> implements PromiseLike<Result<QueryData<Selected, C>>> {}
```

### Properties


```ts
readonly table: string;
```

### constructor


```ts
constructor(
  host: QueryHost,
  table: string,
  state?: QueryState,
  columns?: string,
  cardinality?: Cardinality,
  throws?: boolean,
);
```

### inGroup


```ts
/** Route this query to a shared private collection. Unsupported hosts never fall back to another scope. */
inGroup(groupId: string): QueryBuilder<T, Selected, C>;
```

### select


```ts
select<const Columns extends string = "*">(
  columns?: Columns & Selection<Row<T>, Columns>,
  options?: SelectOptions,
): QueryBuilder<T, Projection<Row<T>, Columns>, C>;
```

### insert


```ts
insert(values: Insert<T> | Insert<T>[]): QueryBuilder<T, Row<T>, "many">;
```

### upsert


```ts
upsert(values: Insert<T> | Insert<T>[]): QueryBuilder<T, Row<T>, "many">;
```

### update


```ts
update(patch: Partial<T>): QueryBuilder<T, Row<T>, "many">;
```

### delete


```ts
delete(): QueryBuilder<T, Row<T>, "many">;
```

### eq


```ts
eq<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

eq<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;
```

### neq


```ts
neq<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

neq<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;
```

### in


```ts
in<K extends QueryField<Row<T>>>(
  field: K,
  values: readonly QueryFieldValue<Row<T>, K>[],
): QueryBuilder<T, Selected, C>;
```

### gt


```ts
gt<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

gt<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;
```

### gte


```ts
gte<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

gte<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;
```

### lt


```ts
lt<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

lt<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;
```

### lte


```ts
lte<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

lte<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;
```

### is


```ts
is<K extends QueryField<Row<T>>>(
  field: K,
  value: null | boolean,
): QueryBuilder<T, Selected, C>;
```

### contains


```ts
contains<K extends QueryField<Row<T>>>(
  field: K,
  value: DeepPartial<QueryFieldValue<Row<T>, K>>,
): QueryBuilder<T, Selected, C>;
```

### containedBy


```ts
containedBy<K extends QueryField<Row<T>>>(
  field: K,
  value: DeepPartial<QueryFieldValue<Row<T>, K>>,
): QueryBuilder<T, Selected, C>;
```

### overlaps


```ts
overlaps<K extends QueryField<Row<T>>>(
  field: K,
  value: FilterValue<QueryFieldValue<Row<T>, K>, "overlaps">,
): QueryBuilder<T, Selected, C>;
```

### like


```ts
like<K extends QueryField<Row<T>>>(
  field: K,
  pattern: string,
): QueryBuilder<T, Selected, C>;
```

### ilike


```ts
ilike<K extends QueryField<Row<T>>>(
  field: K,
  pattern: string,
): QueryBuilder<T, Selected, C>;
```

### textSearch


```ts
textSearch<K extends QueryField<T>>(
  field: K,
  query: string,
): QueryBuilder<T, Selected, C>;
```

### filter


```ts
filter<K extends QueryField<Row<T>>, O extends FilterOperator>(
  field: K,
  op: O,
  value: FilterValue<QueryFieldValue<Row<T>, K>, O> | string,
): QueryBuilder<T, Selected, C>;
```

### not


```ts
not<K extends QueryField<Row<T>>, O extends FilterOperator>(
  field: K,
  op: O,
  value: FilterValue<QueryFieldValue<Row<T>, K>, O> | string,
): QueryBuilder<T, Selected, C>;
```

### or


```ts
/** PostgREST-style alternatives. Other chained filters remain AND conditions. */
or(expression: string): QueryBuilder<T, Selected, C>;
```

### local


```ts
/** Read only from the local verified cache; no relay request is made. */
local(): QueryBuilder<T, Selected, C>;
```

### queue


```ts
/** Sign and save a mutation for explicit offline replay. Requires a signed-in author. */
queue(): QueryBuilder<T, Selected, C>;
```

### page


```ts
/** Timestamp/event-id cursor pagination, newest records first. */
page(
  size: number,
  options?: {
    cursor?: string;
  },
): QueryBuilder<T, Selected, C>;
```

### match


```ts
match(values: Partial<Row<T>>): QueryBuilder<T, Selected, C>;
```

### author


```ts
author(pubkey: string | readonly string[]): QueryBuilder<T, Selected, C>;
```

### order


```ts
order(
  field: QueryField<Row<T>>,
  options?: {
    ascending?: boolean;
    nullsFirst?: boolean;
  },
): QueryBuilder<T, Selected, C>;
```

### limit


```ts
limit(count: number): QueryBuilder<T, Selected, C>;
```

### range


```ts
range(from: number, to: number): QueryBuilder<T, Selected, C>;
```

### all


```ts
/** Explicitly permit an update or delete of every record owned by the signer. */
all(): QueryBuilder<T, Selected, C>;
```

### single


```ts
single(): QueryBuilder<T, Selected, "one">;
```

### maybeSingle


```ts
maybeSingle(): QueryBuilder<T, Selected, "maybe">;
```

### abortSignal


```ts
abortSignal(signal: AbortSignal): QueryBuilder<T, Selected, C>;
```

### throwOnError


```ts
throwOnError(): QueryBuilder<T, Selected, C>;
```

### then


```ts
then<TResult1 = Result<QueryData<Selected, C>>, TResult2 = never>(
  onfulfilled?:
    | ((value: Result<QueryData<Selected, C>>) => TResult1 | PromiseLike<TResult1>)
    | null,
  onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
): Promise<TResult1 | TResult2>;
```


## Supporting declarations

These types appear in public signatures but are not package exports.

### QueryState


```ts
interface QueryState {
  operation: "select" | "insert" | "upsert" | "update" | "delete";
  groupId?: string;
  values?: object[];
  patch?: object;
  predicates: Predicate[];
  authors?: string[];
  order: {
    field: string;
    ascending: boolean;
    nullsFirst?: boolean;
  }[];
  count?: "exact";
  head?: boolean;
  limit?: number;
  range?: [number, number];
  allowAll: boolean;
  returning: boolean;
  signal?: AbortSignal;
  validationError?: NostrbaseError;
  queue?: boolean;
  local?: boolean;
  page?: {
    size: number;
    cursor?: string;
  };
}
```

### QueryHost


```ts
interface QueryHost {
  execute<T extends object>(
    table: string,
    state: QueryState,
  ): Promise<Result<Row<T>[]>>;
  executeInGroup?<T extends object>(
    groupId: string,
    table: string,
    state: QueryState,
  ): Promise<Result<Row<T>[]>>;
}
```