The complete public API of @lakeql/query-builder, generated from the package's TypeScript source.
The main entry point is generateQuery. It turns selected fields, a filter, sorting, and paging into a compiled SQL query. The filter types (Where, Field, FieldOptions) describe the shape of a filter. The helper functions (getSelectFields, normalizeFilter, formatQuery) build and inspect queries.
Comparison operators available for filtering a single field. Only one operator should be set per FieldOptions object.
String operators compare the field value against the provided string. Boolean operators (is/isNot) check for equality with true/false.
Properties
| Name | Type |
|---|---|
| eq? | string |
| neq? | string |
| in? | string |
| notIn? | string |
| lt? | string |
| lte? | string |
| gt? | string |
| gte? | string |
| like? | string |
| notLike? | string |
| is? | boolean |
| isNot? | boolean |
Defines the sort order for a query result.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
TableDefinition | — | — |
The table type used to constrain the field to valid column names. See query-builder for details. | ||
Properties
| Name | Type |
|---|---|
| fieldRequired | SelectExpression< KyselyDatabase<TableDefinition>, keyof KyselyDatabase<TableDefinition> > |
Column name to sort by. Constrained to valid column names from the table type. | |
| directionRequired | "asc" | "desc" |
Sort direction | |
Controls offset-based pagination.
Properties
| Name | Type |
|---|---|
| limit? | number |
Maximum number of rows to return. 100 | |
| offset? | number |
Number of rows to skip before fetching. | |
Parameters for generating an adapter-aware SQL query from GraphQL resolve info.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
TableDefinition | — | — |
The table type definition used by Kysely for type-safe column references. See query-builder for details. | ||
Properties
| Name | Type |
|---|---|
| dialectRequired | QueryDialect |
The query dialect providing adapter-specific SQL generation. | |
| catalogRequired | string |
The catalog name (e.g. “hive”). | |
| schemaRequired | string |
The schema name (e.g. “sales”). | |
| tableRequired | string |
The table name to query. | |
| selectFieldsRequired | readonly string[] |
The column names to select, derived from GraphQL field selections. These are plain field-name strings (as returned by getSelectFields); they are resolved against the table definition when the query is built. | |
| userQueryRequired | Where |
The user-provided filter query (WHERE clause). | |
| paging? | PagingInput |
Pagination parameters (limit and offset). | |
| sortingRequired | SortInput<TableDefinition>[] |
Sort order definitions. | |
| transformFields? | Record<string, string> |
Maps GraphQL field names to database column names. | |
| dateFields? | string[] |
Fields that should be wrapped in adapter-specific timestamp conversion. | |
Parameters for building a single field comparison expression.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
TableDefinition | — | — |
The table type definition. See query-builder for details. | ||
Properties
| Name | Type |
|---|---|
| ebRequired | ExpressionBuilder<KyselyDatabase<TableDefinition>, "tablename"> |
The Kysely expression builder for constructing SQL expressions. | |
| fieldNameRequired | string |
The column name to filter on. | |
| operatorRequired | string |
The comparison operator (eq, neq, lt, like, etc.). | |
| valueRequired | unknown |
The value to compare against. | |
Properties
| Name | Type |
|---|---|
| graphqlInfoRequired | GraphQLResolveInfo |
The GraphQL resolve info from the resolver. | |
| withNodes? | boolean |
When true, looks inside the nodes selection (for Connection types). false | |
A single field condition — a record where the key is the field name and the value is a FieldOptions object describing the comparison.
A recursive filter structure that can contain AND/OR groups, each holding field conditions or further nested groups.
Builds a single field comparison expression for use in WHERE clauses.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
TableDefinition | — | — |
Parameters
| Name | Type |
|---|---|
| getFieldQueryPropsRequired | GetFieldQueryProps<TableDefinition> |
Returns
ExpressionWrapper<
KyselyDatabase<TableDefinition>,
"tablename",
SqlBool
>A Kysely ExpressionWrapper representing the comparison.
Normalizes filter objects by ensuring each field is in its own object within and/or arrays.
Splits multi-field filter objects into separate entries so the query builder can process each field condition independently.
Parameters
| Name | Type |
|---|---|
| filterRequired | Where |
The filter object to normalize. | |
Returns
WhereA normalized filter with individual field entries.
Wraps bare field-level filters into an AND-rooted structure.
If the query already has a single and or or key at the root, it is returned as-is. Otherwise, all entries are combined under an and key.
Parameters
| Name | Type |
|---|---|
| userQueryRequired | Where |
The user-provided filter query. | |
Returns
WhereA normalized query with a logical operator at the root.
Generates a compiled SQL query with pagination metadata using the injected dialect.
The query uses two CTEs internally:
- total_count — provides total_records (total matching rows before paging)
- records — the actual rows based on selectFields , filtering, sorting, and paging
The compiled query is executed by the DataSource adapter which returns the row data.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
TableDefinition | — | — |
Parameters
| Name | Type |
|---|---|
| generateQueryPropsRequired | GenerateQueryProps<TableDefinition> |
Returns
import("kysely").CompiledQuery<{ total_records: number; }>A CompiledQuery ready for execution via the DataSource adapter.
Extracts selected field names from a GraphQL resolve info object.
Parameters
| Name | Type |
|---|---|
| getSelectFieldPropsRequired | GetSelectFieldProps |
Returns
string[]An array of field names to use as SELECT columns.
Logical operators for combining filter conditions.
| Name | Type |
|---|---|
| AND | "and" |
| OR | "or" |
Engine-specific SQL generation strategy for Kysely.
Each adapter provides a dialect that handles identifier quoting, pagination syntax, date functions, and sql-formatter language selection. The dialect is injected into the query builder — the query builder itself contains no adapter-specific SQL logic.
Properties
| Name | Type |
|---|---|
| adapterNameRequired | AdapterName |
Open adapter name identifying the backend this dialect targets. | |
| createAdapterRequired | () => DialectAdapter |
Creates the Kysely dialect adapter (e.g. PostgresAdapter, MssqlAdapter). | |
| createQueryCompilerRequired | () => QueryCompiler |
Creates the Kysely query compiler for the target backend. | |
| createIntrospectorRequired | (db: Kysely<unknown>) => DatabaseIntrospector |
Creates the Kysely database introspector for the target backend. | |
| toUnixTimestampRequired | (field: string) => RawBuilder<unknown> |
Wraps a column name in the backend-specific timestamp-to-unix conversion function. | |
| paginationRequired | (limit: number, offset?: number) => RawBuilder<unknown> |
Returns a raw SQL fragment for limit/offset pagination. | |
| trueLiteralRequired | () => RawBuilder<unknown> |
Backend-specific boolean “true” literal used for the record-present sentinel column in the records CTE. Trino uses TRUE; T-SQL backends (e.g. Fabric) have no boolean literal and use 1. | |
| qualifiedTableRequired | (config: SourceConfig) => string |
Returns the fully-qualified table name with backend-specific quoting. | |