pqb 0.16.0 → 0.16.2

package/dist/index.d.ts

@@ -1507,379 +1507,664 @@ declare class OnQueryBuilder<S extends QueryBase = QueryBase, J extends QueryBas
     _onJsonPathEquals<T extends OnQueryBuilder>(this: T, ...args: OnJsonPathEqualsArgs<T>): T;
 }
 
-declare module './aggregate' {
-    interface SelectAggMethods<T extends Query> {
-        /**
-         * Give the `as` alias for the search, and it becomes possible to select a text with highlights of the matching words or phrases:
-         *
-         * ```ts
-         * db.table
-         *   .search({
-         *     as: 'search',
-         *     in: 'body',
-         *     query: 'query',
-         *   })
-         *   .select({
-         *     highlightedText: (q) => q.headline('search'),
-         *   });
-         * ```
-         *
-         * When searching in the generated `tsvector` column, need to provide a text source to the `headline`:
-         *
-         * ```ts
-         * db.table
-         *   .search({
-         *     as: 'search',
-         *     vector: 'textVector',
-         *     query: 'query',
-         *   })
-         *   .select({
-         *     // `body` is a column name
-         *     highlightedText: (q) => q.headline('search', { text: 'body' }),
-         *   });
-         * ```
-         *
-         * `text` can be a raw SQL, here we are joining multiple columns:
-         *
-         * ```ts
-         * import { raw } from 'orchid-orm';
-         *
-         * db.table
-         *   .search({
-         *     as: 'search',
-         *     vector: 'titleAndBodyVector',
-         *     query: 'query',
-         *   })
-         *   .select({
-         *     highlightedText: (q) =>
-         *       q.headline('search', { text: raw`concat_ws(' ', title, body)` }),
-         *   });
-         * ```
-         *
-         * `headline` supports a string for `options`, see details [in Postgres doc](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-HEADLINE).
-         *
-         * Provide a simple string or a raw SQL:
-         *
-         * ```ts
-         * db.table
-         *   .search({
-         *     as: 'search',
-         *     in: 'body',
-         *     query: 'query',
-         *   })
-         *   .select({
-         *     highlightedText: (q) =>
-         *       q.headline('search', {
-         *         options:
-         *           'MaxFragments=10, MaxWords=7, MinWords=3, StartSel=<<, StopSel=>>',
-         *       }),
-         *   });
-         * ```
-         *
-         * @param search - name of the search to use the query from
-         * @param options - `text` for a text source, `options` for `ts_headline` options
-         */
-        headline(search: string | undefined extends T['meta']['tsQuery'] ? never : Exclude<T['meta']['tsQuery'], undefined>, options?: {
-            text?: SelectableOrExpressionOfType<T, TextColumn>;
-            options?: string | Expression;
-        }): ColumnExpression<TextColumn>;
-    }
-}
-type SearchArg<T extends QueryBase, As extends string> = {
-    as?: As;
-    order?: OrderTsQueryConfig;
-} & ({
-    language?: string | Expression;
-} | {
-    languageColumn?: keyof T['selectable'];
-}) & ({
-    text: string | Expression;
-} | {
-    in: MaybeArray<keyof T['selectable']> | {
-        [K in keyof T['selectable']]?: SearchWeight;
-    };
-} | {
-    vector: {
-        [K in keyof T['selectable']]: T['selectable'][K]['column']['dataType'] extends 'tsvector' ? K : never;
-    }[keyof T['selectable']];
-}) & ({
-    query: string | Expression;
-} | {
-    plainQuery: string | Expression;
-} | {
-    phraseQuery: string | Expression;
-} | {
-    tsQuery: string | Expression;
-});
-type WhereSearchResult<T extends QueryBase, As extends string> = T & {
+type WhereArg<T extends QueryBase> = {
+    [K in keyof T['selectable'] | 'NOT' | 'OR' | 'IN' | 'EXISTS']?: K extends 'NOT' ? MaybeArray<WhereArg<T>> : K extends 'OR' ? MaybeArray<WhereArg<T>>[] : K extends 'IN' ? MaybeArray<{
+        columns: (keyof T['selectable'])[];
+        values: unknown[][] | Query | Expression;
+    }> : K extends keyof T['selectable'] ? T['selectable'][K]['column']['type'] | null | ColumnOperators<T['selectable'], K> | Expression | Query : never;
+} | QueryBase | Expression | ((q: WhereQueryBuilder<T>) => WhereQueryBuilder);
+type WhereArgs<T extends QueryBase> = WhereArg<T>[] | TemplateLiteralArgs;
+type WhereInColumn<T extends QueryBase> = keyof T['selectable'] | [keyof T['selectable'], ...(keyof T['selectable'])[]];
+type WhereInValues<T extends QueryBase, Column extends WhereInColumn<T>> = Column extends keyof T['selectable'] ? T['selectable'][Column]['column']['type'][] | Query | Expression : ({
+    [I in keyof Column]: Column[I] extends keyof T['selectable'] ? T['selectable'][Column[I]]['column']['type'] : never;
+} & {
+    length: Column extends {
+        length: number;
+    } ? Column['length'] : never;
+})[] | Query | Expression;
+type WhereInArg<T extends Pick<Query, 'selectable'>> = {
+    [K in keyof T['selectable']]?: T['selectable'][K]['column']['type'][] | Query | Expression;
+};
+type WhereResult<T extends QueryBase> = T & {
     meta: {
-        tsQuery: string extends As ? never : As;
+        hasWhere: true;
     };
 };
-declare const saveSearchAlias: (q: QueryBase, as: string) => string;
-declare class SearchMethods {
+/**
+ * Adds `where` arguments to query data: SQL template string is added as `RawSQL` object, other arguments are added as is.
+ *
+ * @param q - query object to add the data to
+ * @param args - `where` arguments, may be a template literal
+ */
+declare const addWhere: <T extends QueryBase>(q: T, args: WhereArgs<T>) => WhereResult<T>;
+/**
+ * Adds `where` arguments to query data with a `NOT` keyword: SQL template string is added as `RawSQL` object, other arguments are added as is.
+ *
+ * @param q - query object to add the data to
+ * @param args - `where` arguments, may be a template literal
+ */
+declare const addWhereNot: <T extends QueryBase>(q: T, args: WhereArgs<T>) => WhereResult<T>;
+/**
+ * Adds `where` arguments to query data. Arguments will be separated from each other with `OR`.
+ *
+ * @param q - query object to add the data to
+ * @param args - `where` arguments, may be a template literal
+ */
+declare const addOr: <T extends QueryBase>(q: T, args: WhereArg<T>[]) => WhereResult<T>;
+/**
+ * Adds `where` arguments to query data with a `NOT` keyword. Arguments will be separated from each other with `OR`.
+ *
+ * @param q - query object to add the data to
+ * @param args - `where` arguments, may be a template literal
+ */
+declare const addOrNot: <T extends QueryBase>(q: T, args: WhereArg<T>[]) => WhereResult<T>;
+/**
+ * Process arguments of `whereIn` to add them to query data properly.
+ *
+ * @param q - query object to add the data to.
+ * @param and - `true` to join arguments with `AND`, `false` to join them with `OR.
+ * @param arg - `whereIn` argument: can be a single column name, tuple of column names, or object with column names and values.
+ * @param values - if the `arg` is a column name or a tuple, `values` are the values for the column/columns. If `arg` is an object, `values` are `undefined`.
+ * @param not - adds the `NOT` keyword.
+ */
+declare const addWhereIn: <T extends QueryBase>(q: T, and: boolean, arg: unknown, values: unknown[] | unknown[][] | Query | Expression | undefined, not?: boolean) => WhereResult<T>;
+declare abstract class Where extends QueryBase {
     /**
-     * ## language
+     * Constructing `WHERE` conditions:
      *
-     * By default, the search language is English.
+     * ```ts
+     * db.table.where({
+     *   // column of the current table
+     *   name: 'John',
      *
-     * You can set a different default language in the `createBaseTable` config:
+     *   // table name may be specified, it can be the name of a joined table
+     *   'table.lastName': 'Johnsonuk',
      *
-     * ```ts
-     * import { createBaseTable } from 'orchid-orm';
+     *   // object with operators, see the "column operators" section to see a full list of them:
+     *   age: {
+     *     gt: 30,
+     *     lt: 70,
+     *   },
      *
-     * export const BaseTable = createBaseTable({
-     *   language: 'swedish',
+     *   // where column equals to raw SQL
+     *   column: db.table.sql`raw expression`,
      * });
      * ```
      *
-     * See the list of supported language configs with the SQL:
+     * `undefined` values are ignored, so you can supply a partial object with conditions:
      *
-     * ```sql
-     * SELECT cfgname FROM pg_ts_config;
+     * ```ts
+     * type Params = {
+     *   // allow providing exact age, or lower or greate than
+     *   age?: number | { lt?: number; gt?: number };
+     * };
+     *
+     * const loadRecords = async (params: Params) => {
+     *   // this will load all records if params is an empty object
+     *   const records = await db.table.where(params);
+     * };
      * ```
      *
-     * When performing a search, you can override the default language:
+     * It supports a sub-query that is selecting a single value to compare it with a column:
      *
      * ```ts
-     * db.table.search({
-     *   language: 'finnish',
-     *   in: 'body',
-     *   query: 'query',
+     * db.table.where({
+     *   // compare `someColumn` in one table with the `column` value returned from another query.
+     *   someColumn: db.otherTable.where(...conditions).get('column'),
      * });
      * ```
      *
-     * `language` also accepts a raw SQL.
-     *
-     * The language can be stored in the column of this table, then you can use `languageColumn` to use this column for the search:
+     * `where` can accept other queries and merge their conditions:
      *
      * ```ts
-     * db.table.search({
-     *   // the table has `lang` column, use it for the search
-     *   languageColumn: 'lang',
-     *   in: 'body',
-     *   query: 'query',
-     * });
-     * ```
+     * const otherQuery = db.table.where({ name: 'John' });
      *
-     * ## text vector to search in
+     * db.table.where({ id: 1 }, otherQuery);
+     * // this will produce WHERE "table"."id" = 1 AND "table"."name' = 'John'
+     * ```
      *
-     * The text to search in can be a simple string, or a raw SQL, or a text column, or multiple columns:
+     * `where` supports raw SQL:
      *
      * ```ts
-     * db.table.search({
-     *   // search in the given string
-     *   text: 'simply a string to search in',
-     *   query: 'query',
-     * });
+     * db.table.where`a = b`;
+     *
+     * // or
+     * db.table.where(db.table.sql`a = b`);
      *
+     * // or
      * import { raw } from 'orchid-orm';
      *
-     * db.table.search({
-     *   // raw SQL: join text columns with space
-     *   text: raw`concat_ws(' ', title, body)`,
-     *   query: 'query',
-     * });
+     * db.table.where(raw`a = b`);
+     * ```
      *
-     * db.table.search({
-     *   // search in a single text column
-     *   in: 'body',
-     *   query: 'query',
-     * });
+     * `where` can accept a callback with a specific query builder containing all "where" methods such as `where`, `or`, `whereNot`, `whereIn`, `whereExists`:
      *
-     * db.table.search({
-     *   // search in multiple columns, they are concatenated with `concat_ws` as shown above
-     *   in: ['title', 'body'],
-     *   query: 'query',
-     * });
+     * ```ts
+     * db.table.where((q) =>
+     *   q
+     *     .where({ name: 'Name' })
+     *     .or({ id: 1 }, { id: 2 })
+     *     .whereIn('letter', ['a', 'b', 'c'])
+     *     .whereExists(Message, 'authorId', 'id'),
+     * );
+     * ```
      *
-     * db.table.search({
-     *   // search in multiple columns with different weights. Weight can be A, B, C, or D
-     *   in: {
-     *     title: 'A',
-     *     body: 'B',
-     *   },
-     *   query: 'query',
-     * });
+     * `where` can accept multiple arguments, conditions are joined with `AND`:
+     *
+     * ```ts
+     * db.table.where(
+     *   { id: 1 },
+     *   db.table.where({ name: 'John' }),
+     *   db.table.sql`a = b`,
+     * );
      * ```
      *
-     * For better performance, define a [generated](/guide/migration-column-methods.html#generated) column of `tsvector` type, and use it in the search with `vector` keyword:
+     * ### where special keys
+     *
+     * The object passed to `where` can contain special keys, each of the keys corresponds to its own method and takes the same value as the type of argument of the method.
+     *
+     * For example:
      *
      * ```ts
-     * db.table.search({
-     *   vector: 'titleAndBodyVector',
-     *   query: 'query',
+     * db.table.where({
+     *   NOT: { key: 'value' },
+     *   OR: [{ name: 'a' }, { name: 'b' }],
+     *   IN: {
+     *     columns: ['id', 'name'],
+     *     values: [
+     *       [1, 'a'],
+     *       [2, 'b'],
+     *     ],
+     *   },
      * });
      * ```
      *
-     * ## search query
+     * Using methods instead of this is a shorter and cleaner way, but in some cases, such object keys way may be more convenient.
      *
-     * Read about different search queries in [this Postgres doc](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES).
+     * ```ts
+     * db.table.where({
+     *   // see .whereNot
+     *   NOT: { id: 1 },
+     *   // can be an array:
+     *   NOT: [{ id: 1 }, { id: 2 }],
      *
-     * `search` method can accept one of the following queries:
+     *   // see .or
+     *   OR: [{ name: 'a' }, { name: 'b' }],
+     *   // can be an array:
+     *   // this will give id = 1 AND id = 2 OR id = 3 AND id = 4
+     *   OR: [
+     *     [{ id: 1 }, { id: 2 }],
+     *     [{ id: 3 }, { id: 4 }],
+     *   ],
      *
-     * - `query`: corresponds to `websearch_to_tsquery` in Postgres, good to use by default
-     * - `plainQuery`: corresponds to `plainto_tsquery`
-     * - `phraseQuery`: corresponds to `phraseto_tsquery`
-     * - `tsQuery`: corresponds to `to_tsquery`
+     *   // see .in, the key syntax requires an object with columns and values
+     *   IN: {
+     *     columns: ['id', 'name'],
+     *     values: [
+     *       [1, 'a'],
+     *       [2, 'b'],
+     *     ],
+     *   },
+     *   // can be an array:
+     *   IN: [
+     *     {
+     *       columns: ['id', 'name'],
+     *       values: [
+     *         [1, 'a'],
+     *         [2, 'b'],
+     *       ],
+     *     },
+     *     { columns: ['someColumn'], values: [['foo', 'bar']] },
+     *   ],
+     * });
+     * ```
      *
-     * The `query` (`websearch_to_tsquery`) can work with any user input, while other query kinds require a specific format and will fail for invalid input.
+     * ## column operators
      *
-     * Each query kind accepts a string or a raw SQL.
+     * `where` argument can take an object where the key is the name of the operator and the value is its argument.
+     *
+     * Different types of columns support different sets of operators.
+     *
+     * All column operators can take a value of the same type as the column, a sub-query, or a raw SQL expression:
      *
      * ```ts
-     * import { raw } from 'orchid-orm';
+     * db.table.where({
+     *   numericColumn: {
+     *     // lower than 5
+     *     lt: 5,
      *
-     * db.table.search({
-     *   vector: 'titleAndBodyVector',
-     *   // can accept raw SQL:
-     *   phraseQuery: raw`'The Fat Rats'`,
+     *     // lower than the value returned by sub-query
+     *     lt: OtherTable.select('someNumber').take(),
+     *
+     *     // raw SQL expression produces WHERE "numericColumn" < "otherColumn" + 10
+     *     lt: db.table.sql`"otherColumn" + 10`,
+     *   },
      * });
      * ```
      *
-     * ## order by search rank
+     * ### Any type of column operators
      *
-     * Read about search ranking in [this Postgres doc](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING).
+     * `equals` is a simple `=` operator, it may be useful for comparing column value with JSON object:
      *
-     * Set `order: true` to order results by the search rank:
+     * ```ts
+     * db.table.where({
+     *   // this will fail because an object with operators is expected
+     *   jsonColumn: someObject,
+     *
+     *   // use this instead:
+     *   jsonColumn: { equals: someObject },
+     * });
+     * ```
+     *
+     * `not` is `!=` (or `<>`) not equal operator:
      *
      * ```ts
-     * db.table.search({
-     *   in: 'body',
-     *   query: 'query',
-     *   // will add ORDER BY ts_rank(to_tsvector('english', body)) DESC
-     *   order: true,
+     * db.table.where({
+     *   anyColumn: { not: value },
      * });
      * ```
      *
-     * To order with `ts_rank_cd` instead of `ts_rank`, set `coverDensity: true`:
+     * `in` is for the `IN` operator to check if the column value is included in a list of values.
+     *
+     * Takes an array of the same type as a column, a sub-query that returns a list of values, or a raw SQL expression that returns a list.
      *
      * ```ts
-     * db.table.search({
-     *   in: 'body',
-     *   query: 'query',
-     *   // will add ORDER BY ts_rank_cd(to_tsvector('english', body)) DESC
-     *   order: {
-     *     coverDensity: true,
+     * db.table.where({
+     *   column: {
+     *     in: ['a', 'b', 'c'],
+     *
+     *     // WHERE "column" IN (SELECT "column" FROM "otherTable")
+     *     in: OtherTable.select('column'),
+     *
+     *     in: db.table.sql`('a', 'b')`,
      *   },
      * });
      * ```
      *
-     * Other options are:
+     * `notIn` is for the `NOT IN` operator, and takes the same arguments as `in`
+     *
+     * ### Numeric, Date, and Time column operators
+     *
+     * To compare numbers, dates, and times.
+     *
+     * `lt` is for `<` (lower than)
+     *
+     * `lte` is for `<=` (lower than or equal)
+     *
+     * `gt` is for `>` (greater than)
+     *
+     * `gte` is for `>=` (greater than or equal)
      *
      * ```ts
-     * db.table.search({
-     *   in: 'body',
-     *   query: 'query',
-     *   order: {
-     *     // weights for D, C, B, A:
-     *     weights: [0.1, 0.2, 0.4, 1],
-     *     // by default, rank ignores the document length
-     *     // change rank behavior by providing here a special number
-     *     normalization: 32,
-     *     // it's possible to change the order direction:
-     *     dir: 'ASC', // DESC by default
+     * db.table.where({
+     *   numericColumn: {
+     *     gt: 5,
+     *     lt: 10,
+     *   },
+     *
+     *   date: {
+     *     lte: new Date(),
+     *   },
+     *
+     *   time: {
+     *     gte: new Date(),
      *   },
      * });
      * ```
      *
-     * Giving the `as` alias for the search allows to set the ordering in the `order` method:
+     * `between` also works with numeric, dates, and time columns, it takes an array of two elements.
+     *
+     * Both elements can be of the same type as a column, a sub-query, or a raw SQL expression.
      *
      * ```ts
-     * db.table
-     *   .search({
-     *     as: 'search',
-     *     in: 'body',
-     *     query: 'query',
-     *   })
-     *   .order({
-     *     // can be `search: true` for defaults
-     *     search: {
-     *       // same options as above
-     *       coverDensity: true,
-     *       weights: [0.1, 0.2, 0.4, 1.0],
-     *       normalization: 32,
-     *       dir: 'ASC',
-     *     },
-     *   });
+     * db.table.where({
+     *   column: {
+     *     // simple values
+     *     between: [1, 10],
+     *
+     *     // sub-query and raw SQL expression
+     *     between: [OtherTable.select('column').take(), db.table.sql`2 + 2`],
+     *   },
+     * });
      * ```
      *
-     * @param arg - search config
+     * ### Text column operators
+     *
+     * For `text`, `char`, `varchar`, and `json` columns.
+     *
+     * `json` is stored as text, so it has text operators. Use the `jsonb` type for JSON operators.
+     *
+     * Takes a string, or sub-query returning string, or raw SQL expression as well as other operators.
+     *
+     * ```ts
+     * db.table.where({
+     *   textColumn: {
+     *     // WHERE "textColumn" LIKE '%string%'
+     *     contains: 'string',
+     *     // WHERE "textColumn" ILIKE '%string%'
+     *     containsInsensitive: 'string',
+     *     // WHERE "textColumn" LIKE 'string%'
+     *     startsWith: 'string',
+     *     // WHERE "textColumn" ILIKE 'string%'
+     *     startsWithInsensitive: 'string',
+     *     // WHERE "textColumn" LIKE '%string'
+     *     endsWith: 'string',
+     *     // WHERE "textColumn" ILIKE '%string'
+     *     endsWithInsensitive: 'string',
+     *   },
+     * });
+     * ```
+     *
+     * ### JSONB column operators
+     *
+     * For the `jsonb` column, note that the `json` type has text operators instead.
+     *
+     * `jsonPath` operator: compare a column value under a given JSON path with the provided value.
+     *
+     * Value can be of any type to compare with JSON value, or it can be a sub-query or a raw SQL expression.
+     *
+     * ```ts
+     * db.table.where({
+     *   jsonbColumn: {
+     *     jsonPath: [
+     *       '$.name', // first element is JSON path
+     *       '=', // second argument is comparison operator
+     *       'value', // third argument is a value to compare with
+     *     ],
+     *   },
+     * });
+     * ```
+     *
+     * `jsonSupersetOf`: check if the column value is a superset of provided value.
+     *
+     * For instance, it is true if the column has JSON `{ "a": 1, "b": 2 }` and provided value is `{ "a": 1 }`.
+     *
+     * Takes the value of any type, or sub query which returns a single value, or a raw SQL expression.
+     *
+     * ```ts
+     * db.table.where({
+     *   jsonbColumn: {
+     *     jsonSupersetOf: { a: 1 },
+     *   },
+     * });
+     * ```
+     *
+     * `jsonSubsetOf`: check if the column value is a subset of provided value.
+     *
+     * For instance, it is true if the column has JSON `{ "a": 1 }` and provided value is `{ "a": 1, "b": 2 }`.
+     *
+     * Takes the value of any type, or sub query which returns a single value, or a raw SQL expression.
+     *
+     * ```ts
+     * db.table.where({
+     *   jsonbColumn: {
+     *     jsonSupersetOf: { a: 1 },
+     *   },
+     * });
+     * ```
+     *
+     * @param args - {@link WhereArgs}
      */
-    search<T extends Query, As extends string>(this: T, arg: SearchArg<T, As>): WhereSearchResult<T, As>;
-    _search<T extends Query, As extends string>(this: T, arg: SearchArg<T, As>): WhereSearchResult<T, As>;
-}
-
-type WhereArg<T extends QueryBase> = {
-    [K in keyof T['selectable'] | 'NOT' | 'OR' | 'IN' | 'EXISTS' | 'SEARCH']?: K extends 'NOT' ? MaybeArray<WhereArg<T>> : K extends 'OR' ? MaybeArray<WhereArg<T>>[] : K extends 'IN' ? MaybeArray<{
-        columns: (keyof T['selectable'])[];
-        values: unknown[][] | Query | Expression;
-    }> : K extends 'SEARCH' ? MaybeArray<SearchArg<T, never>> : K extends keyof T['selectable'] ? T['selectable'][K]['column']['type'] | null | ColumnOperators<T['selectable'], K> | Expression : never;
-} | QueryBase | Expression | ((q: WhereQueryBuilder<T>) => WhereQueryBuilder);
-type WhereArgs<T extends QueryBase> = WhereArg<T>[] | TemplateLiteralArgs;
-type WhereInColumn<T extends QueryBase> = keyof T['selectable'] | [keyof T['selectable'], ...(keyof T['selectable'])[]];
-type WhereInValues<T extends QueryBase, Column extends WhereInColumn<T>> = Column extends keyof T['selectable'] ? T['selectable'][Column]['column']['type'][] | Query | Expression : ({
-    [I in keyof Column]: Column[I] extends keyof T['selectable'] ? T['selectable'][Column[I]]['column']['type'] : never;
-} & {
-    length: Column extends {
-        length: number;
-    } ? Column['length'] : never;
-})[] | Query | Expression;
-type WhereResult<T extends QueryBase> = T & {
-    meta: {
-        hasWhere: true;
-    };
-};
-type WhereInArg<T extends Pick<Query, 'selectable'>> = {
-    [K in keyof T['selectable']]?: T['selectable'][K]['column']['type'][] | Query | Expression;
-};
-declare const addWhere: <T extends QueryBase>(q: T, args: WhereArgs<T>) => WhereResult<T>;
-declare const addWhereNot: <T extends QueryBase>(q: T, args: WhereArgs<T>) => WhereResult<T>;
-declare const addOr: <T extends QueryBase>(q: T, args: WhereArg<T>[]) => WhereResult<T>;
-declare const addOrNot: <T extends QueryBase>(q: T, args: WhereArg<T>[]) => WhereResult<T>;
-declare const addWhereIn: <T extends QueryBase>(q: T, and: boolean, arg: unknown, values: unknown[] | unknown[][] | Query | Expression | undefined, not?: boolean) => WhereResult<T>;
-declare abstract class Where extends QueryBase {
     where<T extends Where>(this: T, ...args: WhereArgs<T>): WhereResult<T>;
     _where<T extends Where>(this: T, ...args: WhereArgs<T>): WhereResult<T>;
+    /**
+     * `whereNot` takes the same arguments as `where` and prepends them with `NOT` in SQL
+     *
+     * ```ts
+     * // find records of different colors than red
+     * db.table.whereNot({ color: 'red' });
+     * ```
+     *
+     * @param args - {@link WhereArgs}
+     */
     whereNot<T extends Where>(this: T, ...args: WhereArgs<T>): WhereResult<T>;
     _whereNot<T extends Where>(this: T, ...args: WhereArgs<T>): WhereResult<T>;
+    /**
+     * `and` is an alias for {@link where} to make it look closer to SQL:
+     *
+     * ```ts
+     * db.table.where({ id: 1 }).and({ name: 'John' });
+     * ```
+     *
+     * @param args - {@link WhereArgs}
+     */
     and<T extends Where>(this: T, ...args: WhereArgs<T>): WhereResult<T>;
     _and<T extends Where>(this: T, ...args: WhereArgs<T>): WhereResult<T>;
+    /**
+     * `andNot` is an alias for `whereNot`.
+     *
+     * @param args - {@link WhereArgs}
+     */
     andNot<T extends Where>(this: T, ...args: WhereArgs<T>): WhereResult<T>;
     _andNot<T extends Where>(this: T, ...args: WhereArgs<T>): WhereResult<T>;
+    /**
+     * `or` is accepting the same arguments as {@link where}, joining arguments with `OR`.
+     *
+     * Columns in single arguments are still joined with `AND`.
+     *
+     * The database is processing `AND` before `OR`, so this should be intuitively clear.
+     *
+     * ```ts
+     * db.table.or({ id: 1, color: 'red' }, { id: 2, color: 'blue' });
+     * ```
+     *
+     * This query will produce such SQL (simplified):
+     *
+     * ```sql
+     * SELECT * FROM "table"
+     * WHERE id = 1 AND color = 'red'
+     *    OR id = 2 AND color = 'blue'
+     * ```
+     *
+     * @param args - {@link WhereArgs} will be joined with `OR`
+     */
     or<T extends Where>(this: T, ...args: WhereArg<T>[]): WhereResult<T>;
     _or<T extends Where>(this: T, ...args: WhereArg<T>[]): WhereResult<T>;
+    /**
+     * `orNot` takes the same arguments as {@link or}, and prepends each condition with `NOT` just as {@link whereNot} does.
+     *
+     * @param args - {@link WhereArgs} will be prefixed with `NOT` and joined with `OR`
+     */
     orNot<T extends Where>(this: T, ...args: WhereArg<T>[]): WhereResult<T>;
     _orNot<T extends Where>(this: T, ...args: WhereArg<T>[]): WhereResult<T>;
+    /**
+     * `whereIn` and related methods are for the `IN` operator to check for inclusion in a list of values.
+     *
+     * When used with a single column it works equivalent to the `in` column operator:
+     *
+     * ```ts
+     * db.table.whereIn('column', [1, 2, 3]);
+     * // the same as:
+     * db.table.where({ column: [1, 2, 3] });
+     * ```
+     *
+     * `whereIn` can support a tuple of columns, that's what the `in` operator cannot support:
+     *
+     * ```ts
+     * db.table.whereIn(
+     *   ['id', 'name'],
+     *   [
+     *     [1, 'Alice'],
+     *     [2, 'Bob'],
+     *   ],
+     * );
+     * ```
+     *
+     * It supports sub query which should return records with columns of the same type:
+     *
+     * ```ts
+     * db.table.whereIn(['id', 'name'], OtherTable.select('id', 'name'));
+     * ```
+     *
+     * It supports raw SQL expression:
+     *
+     * ```ts
+     * db.table.whereIn(['id', 'name'], db.table.sql`((1, 'one'), (2, 'two'))`);
+     * ```
+     *
+     * @param column - one column name, or array of column names
+     * @param values - array of values, or a query to load values, or a raw SQL. Tuple of such values in case of multiple columns.
+     */
     whereIn<T extends Where, Column extends WhereInColumn<T>>(this: T, column: Column, values: WhereInValues<T, Column>): WhereResult<T>;
+    /**
+     * See {@link whereIn}.
+     *
+     * @param arg - object where keys are column names, and values are an array of column values, or a query returning column values, or a raw SQL.
+     */
     whereIn<T extends Where>(this: T, arg: WhereInArg<T>): WhereResult<T>;
     _whereIn<T extends Where, Column extends WhereInColumn<T>>(this: T, column: Column, values: WhereInValues<T, Column>): WhereResult<T>;
     _whereIn<T extends Where>(this: T, arg: WhereInArg<T>): WhereResult<T>;
+    /**
+     * Takes the same arguments as {@link whereIn}.
+     * Add a `WHERE IN` condition prefixed with `OR` to the query:
+     *
+     * ```ts
+     * db.table.whereIn('a', [1, 2, 3]).orWhereIn('b', ['one', 'two']);
+     * ```
+     *
+     * @param column - one column name, or array of column names
+     * @param values - array of values, or a query to load values, or a raw SQL. Tuple of such values in case of multiple columns.
+     */
     orWhereIn<T extends Where, Column extends WhereInColumn<T>>(this: T, column: Column, values: WhereInValues<T, Column>): WhereResult<T>;
+    /**
+     * See {@link orWhereIn}.
+     *
+     * @param arg - object where keys are column names, and values are an array of column values, or a query returning column values, or a raw SQL.
+     */
     orWhereIn<T extends Where>(this: T, arg: WhereInArg<T>): WhereResult<T>;
     _orWhereIn<T extends Where, Column extends WhereInColumn<T>>(this: T, column: Column, values: WhereInValues<T, Column>): WhereResult<T>;
     _orWhereIn<T extends Where>(this: T, arg: WhereInArg<T>): WhereResult<T>;
+    /**
+     * Acts as `whereIn`, but negates the condition with `NOT`:
+     *
+     * ```ts
+     * db.table.whereNotIn('color', ['red', 'green', 'blue']);
+     * ```
+     *
+     * @param column - one column name, or array of column names
+     * @param values - array of values, or a query to load values, or a raw SQL. Tuple of such values in case of multiple columns.
+     */
     whereNotIn<T extends Where, Column extends WhereInColumn<T>>(this: T, column: Column, values: WhereInValues<T, Column>): WhereResult<T>;
+    /**
+     * See {@link whereNotIn}.
+     *
+     * @param arg - object where keys are column names, and values are an array of column values, or a query returning column values, or a raw SQL.
+     */
     whereNotIn<T extends Where>(this: T, arg: WhereInArg<T>): WhereResult<T>;
     _whereNotIn<T extends Where, Column extends WhereInColumn<T>>(this: T, column: Column, values: WhereInValues<T, Column>): WhereResult<T>;
     _whereNotIn<T extends Where>(this: T, arg: WhereInArg<T>): WhereResult<T>;
+    /**
+     * Acts as `whereIn`, but prepends `OR` to the condition and negates it with `NOT`:
+     *
+     * ```ts
+     * db.table.whereNotIn('a', [1, 2, 3]).orWhereNoIn('b', ['one', 'two']);
+     * ```
+     *
+     * @param column - one column name, or array of column names
+     * @param values - array of values, or a query to load values, or a raw SQL. Tuple of such values in case of multiple columns.
+     */
     orWhereNotIn<T extends Where, Column extends WhereInColumn<T>>(this: T, column: Column, values: WhereInValues<T, Column>): WhereResult<T>;
+    /**
+     * See {@link orWhereNotIn}.
+     *
+     * @param arg - object where keys are column names, and values are an array of column values, or a query returning column values, or a raw SQL.
+     */
     orWhereNotIn<T extends Where>(this: T, arg: WhereInArg<T>): WhereResult<T>;
     _orWhereNotIn<T extends Where, Column extends WhereInColumn<T>>(this: T, column: Column, values: WhereInValues<T, Column>): WhereResult<T>;
     _orWhereNotIn<T extends Where>(this: T, arg: WhereInArg<T>): WhereResult<T>;
+    /**
+     * `whereExists` is for support of the `WHERE EXISTS (query)` clause.
+     *
+     * This method is accepting the same arguments as `join`, see the {@link Join.join} section for more details.
+     *
+     * ```ts
+     * // find users who have accounts
+     * // find by a relation name if it's defined
+     * db.user.whereExists('account');
+     *
+     * // find using a table and a join conditions
+     * db.user.whereExists(db.account, 'account.id', 'user.id');
+     *
+     * // find using a query builder in a callback:
+     * db.user.whereExists(db.account, (q) => q.on('account.id', '=', 'user.id'));
+     * ```
+     *
+     * @param arg - relation name, or a query object, or a `with` table alias, or a callback returning a query object.
+     * @param args - no arguments needed when the first argument is a relation name, or conditions to join the table with.
+     */
     whereExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, ...args: JoinArgs<T, Arg>): WhereResult<T>;
+    /**
+     * See {@link whereExists}.
+     *
+     * @param arg - relation name, or a query object, or a `with` table alias, or a callback returning a query object.
+     * @param cb - callback with a query builder to join the table.
+     */
     whereExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, cb: JoinCallback<T, Arg>): WhereResult<T>;
     _whereExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, ...args: JoinArgs<T, Arg>): WhereResult<T>;
     _whereExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, cb: JoinCallback<T, Arg>): WhereResult<T>;
+    /**
+     * Acts as `whereExists`, but prepends the condition with `OR`:
+     *
+     * ```ts
+     * // find users who have an account or a profile,
+     * // imagine that the user has both `account` and `profile` relations defined.
+     * db.user.whereExist('account').orWhereExists('profile');
+     * ```
+     *
+     * @param arg - relation name, or a query object, or a `with` table alias, or a callback returning a query object.
+     * @param args - no arguments needed when the first argument is a relation name, or conditions to join the table with.
+     */
     orWhereExists<T extends Where, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): WhereResult<T>;
+    /**
+     * See {@link orWhereExists}.
+     *
+     * @param arg - relation name, or a query object, or a `with` table alias, or a callback returning a query object.
+     * @param cb - callback with a query builder to join the table.
+     */
     orWhereExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, cb: JoinCallback<T, Arg>): WhereResult<T>;
     _orWhereExists<T extends Where, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): WhereResult<T>;
     _orWhereExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, cb: JoinCallback<T, Arg>): WhereResult<T>;
+    /**
+     * Acts as `whereExists`, but negates the condition with `NOT`:
+     *
+     * ```ts
+     * // find users who don't have an account,
+     * // image that the user `belongsTo` or `hasOne` account.
+     * db.user.whereNotExist('account');
+     * ```
+     *
+     * @param arg - relation name, or a query object, or a `with` table alias, or a callback returning a query object.
+     * @param args - no arguments needed when the first argument is a relation name, or conditions to join the table with.
+     */
     whereNotExists<T extends Where, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): WhereResult<T>;
+    /**
+     * See {@link whereNotExists}.
+     *
+     * @param arg - relation name, or a query object, or a `with` table alias, or a callback returning a query object.
+     * @param cb - callback with a query builder to join the table.
+     */
     whereNotExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, cb: JoinCallback<T, Arg>): WhereResult<T>;
     _whereNotExists<T extends Where, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): WhereResult<T>;
     _whereNotExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, cb: JoinCallback<T, Arg>): WhereResult<T>;
+    /**
+     * Acts as `whereExists`, but prepends the condition with `OR` and negates it with `NOT`:
+     *
+     * ```ts
+     * // find users who don't have an account OR who don't have a profile
+     * // imagine that the user has both `account` and `profile` relations defined.
+     * db.user.whereNotExists('account').orWhereNotExists('profile');
+     * ```
+     *
+     * @param arg - relation name, or a query object, or a `with` table alias, or a callback returning a query object.
+     * @param args - no arguments needed when the first argument is a relation name, or conditions to join the table with.
+     */
     orWhereNotExists<T extends Where, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): WhereResult<T>;
+    /**
+     * See {@link orWhereNotExists}.
+     *
+     * @param arg - relation name, or a query object, or a `with` table alias, or a callback returning a query object.
+     * @param cb - callback with a query builder to join the table.
+     */
     orWhereNotExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, cb: JoinCallback<T, Arg>): WhereResult<T>;
     _orWhereNotExists<T extends Where, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): WhereResult<T>;
     _orWhereNotExists<T extends Where, Arg extends JoinFirstArg<T>>(this: T, arg: Arg, cb: JoinCallback<T, Arg>): WhereResult<T>;
@@ -3325,169 +3610,472 @@ declare class Update {
      *
      * If `.select` and `.take`, `.find`, or similar were specified before the update it will return one updated record.
      *
-     * For a column value you can provide a specific value, raw SQL, a query object that returns a single value, or a callback with a sub-query.
+     * For a column value you can provide a specific value, raw SQL, a query object that returns a single value, or a callback with a sub-query.
+     *
+     * ```ts
+     * // returns number of updated records by default
+     * const updatedCount = await db.table
+     *   .where({ name: 'old name' })
+     *   .update({ name: 'new name' });
+     *
+     * // returning only `id`
+     * const id = await db.table.find(1).get('id').update({ name: 'new name' });
+     *
+     * // `selectAll` + `find` will return a full record
+     * const oneFullRecord = await db.table
+     *   .selectAll()
+     *   .find(1)
+     *   .update({ name: 'new name' });
+     *
+     * // `selectAll` + `where` will return array of full records
+     * const recordsArray = await db.table
+     *   .select('id', 'name')
+     *   .where({ id: 1 })
+     *   .update({ name: 'new name' });
+     *
+     * await db.table.where({ ...conditions }).update({
+     *   // set the column to a specific value
+     *   column1: 123,
+     *
+     *   // use raw SQL to update the column
+     *   column2: db.table.sql`2 + 2`,
+     *
+     *   // use query that returns a single value
+     *   // returning multiple values will result in Postgres error
+     *   column3: db.otherTable.get('someColumn'),
+     *
+     *   // select a single value from a related record
+     *   fromRelation: (q) => q.relatedTable.get('someColumn'),
+     *
+     *   // set a new value to the `.foo.bar` path into a JSON column
+     *   jsonColumn: (q) => q.jsonSet('jsonColumn', ['foo', 'bar'], 'new value'),
+     * });
+     * ```
+     *
+     * `null` value will set a column to `NULL`, but the `undefined` value will be ignored:
+     *
+     * ```ts
+     * db.table.findBy({ id: 1 }).update({
+     *   name: null, // updates to null
+     *   age: undefined, // skipped, no effect
+     * });
+     * ```
+     *
+     * @param arg - data to update records with, may have specific values, raw SQL, queries, or callbacks with sub-queries.
+     */
+    update<T extends Query>(this: T, arg: UpdateArg<T>): UpdateResult<T>;
+    _update<T extends Query>(this: T, arg: UpdateArg<T>): UpdateResult<T>;
+    /**
+     * `updateRaw` is for updating records with raw expression.
+     *
+     * The behavior is the same as a regular `update` method has:
+     * `find` or `where` must precede calling this method,
+     * it returns an updated count by default,
+     * you can customize returning data by using `select`.
+     *
+     * ```ts
+     * const value = 'new name';
+     *
+     * // update with SQL template string
+     * const updatedCount = await db.table.find(1).updateRaw`name = ${value}`;
+     *
+     * // or update with `sql` function:
+     * await db.table.find(1).updateRaw(db.table.sql`name = ${value}`);
+     * ```
+     * @param args - raw SQL via a template string or by using a `sql` method
+     */
+    updateRaw<T extends Query>(this: T, ...args: UpdateRawArgs<T>): UpdateResult<T>;
+    _updateRaw<T extends Query>(this: T, ...args: UpdateRawArgs<T>): UpdateResult<T>;
+    /**
+     * To make sure that at least one row was updated use `updateOrThrow`:
+     *
+     * ```ts
+     * import { NotFoundError } from 'pqb';
+     *
+     * try {
+     *   // updatedCount is guaranteed to be greater than 0
+     *   const updatedCount = await db.table
+     *     .where(conditions)
+     *     .updateOrThrow({ name: 'name' });
+     *
+     *   // updatedRecords is guaranteed to be a non-empty array
+     *   const updatedRecords = await db.table
+     *     .where(conditions)
+     *     .select('id')
+     *     .updateOrThrow({ name: 'name' });
+     * } catch (err) {
+     *   if (err instanceof NotFoundError) {
+     *     // handle error
+     *   }
+     * }
+     * ```
+     *
+     * @param arg - data to update records with, may have specific values, raw SQL, queries, or callbacks with sub-queries.
+     */
+    updateOrThrow<T extends Query>(this: T, arg: UpdateArg<T>): UpdateResult<T>;
+    _updateOrThrow<T extends Query>(this: T, arg: UpdateArg<T>): UpdateResult<T>;
+    /**
+     * Increments a column value by the specified amount. Optionally takes `returning` argument.
+     *
+     * ```ts
+     * // increment numericColumn column by 1, return updated records
+     * const result = await db.table
+     *   .selectAll()
+     *   .where(...conditions)
+     *   .increment('numericColumn');
+     *
+     * // increment someColumn by 5 and otherColumn by 10, return updated records
+     * const result2 = await db.table
+     *   .selectAll()
+     *   .where(...conditions)
+     *   .increment({
+     *     someColumn: 5,
+     *     otherColumn: 10,
+     *   });
+     * ```
+     *
+     * @param data - name of the column to increment, or an object with columns and values to add
+     */
+    increment<T extends Query>(this: T, data: ChangeCountArg<T>): UpdateResult<T>;
+    _increment<T extends Query>(this: T, data: ChangeCountArg<T>): UpdateResult<T>;
+    /**
+     * Decrements a column value by the specified amount. Optionally takes `returning` argument.
+     *
+     * ```ts
+     * // decrement numericColumn column by 1, return updated records
+     * const result = await db.table
+     *   .selectAll()
+     *   .where(...conditions)
+     *   .decrement('numericColumn');
+     *
+     * // decrement someColumn by 5 and otherColumn by 10, return updated records
+     * const result2 = await db.table
+     *   .selectAll()
+     *   .where(...conditions)
+     *   .decrement({
+     *     someColumn: 5,
+     *     otherColumn: 10,
+     *   });
+     * ```
+     *
+     * @param data - name of the column to decrement, or an object with columns and values to subtract
+     */
+    decrement<T extends Query>(this: T, data: ChangeCountArg<T>): UpdateResult<T>;
+    _decrement<T extends Query>(this: T, data: ChangeCountArg<T>): UpdateResult<T>;
+}
+
+type IsolationLevel = 'SERIALIZABLE' | 'REPEATABLE READ' | 'READ COMMITTED' | 'READ UNCOMMITTED';
+type TransactionOptions = {
+    level: IsolationLevel;
+    readOnly?: boolean;
+    deferrable?: boolean;
+};
+declare class Transaction {
+    transaction<T extends Query, Result>(this: T, cb: () => Promise<Result>): Promise<Result>;
+    transaction<T extends Query, Result>(this: T, options: IsolationLevel | TransactionOptions, cb: () => Promise<Result>): Promise<Result>;
+}
+
+declare module './aggregate' {
+    interface SelectAggMethods<T extends Query> {
+        /**
+         * Give the `as` alias for the search, and it becomes possible to select a text with highlights of the matching words or phrases:
+         *
+         * ```ts
+         * db.table
+         *   .search({
+         *     as: 'search',
+         *     in: 'body',
+         *     query: 'query',
+         *   })
+         *   .select({
+         *     highlightedText: (q) => q.headline('search'),
+         *   });
+         * ```
+         *
+         * When searching in the generated `tsvector` column, need to provide a text source to the `headline`:
+         *
+         * ```ts
+         * db.table
+         *   .search({
+         *     as: 'search',
+         *     vector: 'textVector',
+         *     query: 'query',
+         *   })
+         *   .select({
+         *     // `body` is a column name
+         *     highlightedText: (q) => q.headline('search', { text: 'body' }),
+         *   });
+         * ```
+         *
+         * `text` can be a raw SQL, here we are joining multiple columns:
+         *
+         * ```ts
+         * import { raw } from 'orchid-orm';
+         *
+         * db.table
+         *   .search({
+         *     as: 'search',
+         *     vector: 'titleAndBodyVector',
+         *     query: 'query',
+         *   })
+         *   .select({
+         *     highlightedText: (q) =>
+         *       q.headline('search', { text: raw`concat_ws(' ', title, body)` }),
+         *   });
+         * ```
+         *
+         * `headline` supports a string for `options`, see details [in Postgres doc](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-HEADLINE).
+         *
+         * Provide a simple string or a raw SQL:
+         *
+         * ```ts
+         * db.table
+         *   .search({
+         *     as: 'search',
+         *     in: 'body',
+         *     query: 'query',
+         *   })
+         *   .select({
+         *     highlightedText: (q) =>
+         *       q.headline('search', {
+         *         options:
+         *           'MaxFragments=10, MaxWords=7, MinWords=3, StartSel=<<, StopSel=>>',
+         *       }),
+         *   });
+         * ```
+         *
+         * @param search - name of the search to use the query from
+         * @param options - `text` for a text source, `options` for `ts_headline` options
+         */
+        headline(search: string | undefined extends T['meta']['tsQuery'] ? never : Exclude<T['meta']['tsQuery'], undefined>, options?: {
+            text?: SelectableOrExpressionOfType<T, TextColumn>;
+            options?: string | Expression;
+        }): ColumnExpression<TextColumn>;
+    }
+}
+type SearchArg<T extends QueryBase, As extends string> = {
+    as?: As;
+    order?: OrderTsQueryConfig;
+} & ({
+    language?: string | Expression;
+} | {
+    languageColumn?: keyof T['selectable'];
+}) & ({
+    text: string | Expression;
+} | {
+    in: MaybeArray<keyof T['selectable']> | {
+        [K in keyof T['selectable']]?: SearchWeight;
+    };
+} | {
+    vector: {
+        [K in keyof T['selectable']]: T['selectable'][K]['column']['dataType'] extends 'tsvector' ? K : never;
+    }[keyof T['selectable']];
+}) & ({
+    query: string | Expression;
+} | {
+    plainQuery: string | Expression;
+} | {
+    phraseQuery: string | Expression;
+} | {
+    tsQuery: string | Expression;
+});
+type WhereSearchResult<T extends QueryBase, As extends string> = T & {
+    meta: {
+        tsQuery: string extends As ? never : As;
+    };
+};
+declare const saveSearchAlias: (q: QueryBase, as: string) => string;
+declare class SearchMethods {
+    /**
+     * ## language
+     *
+     * By default, the search language is English.
+     *
+     * You can set a different default language in the `createBaseTable` config:
+     *
+     * ```ts
+     * import { createBaseTable } from 'orchid-orm';
+     *
+     * export const BaseTable = createBaseTable({
+     *   language: 'swedish',
+     * });
+     * ```
+     *
+     * See the list of supported language configs with the SQL:
+     *
+     * ```sql
+     * SELECT cfgname FROM pg_ts_config;
+     * ```
+     *
+     * When performing a search, you can override the default language:
+     *
+     * ```ts
+     * db.table.search({
+     *   language: 'finnish',
+     *   in: 'body',
+     *   query: 'query',
+     * });
+     * ```
+     *
+     * `language` also accepts a raw SQL.
+     *
+     * The language can be stored in the column of this table, then you can use `languageColumn` to use this column for the search:
      *
      * ```ts
-     * // returns number of updated records by default
-     * const updatedCount = await db.table
-     *   .where({ name: 'old name' })
-     *   .update({ name: 'new name' });
+     * db.table.search({
+     *   // the table has `lang` column, use it for the search
+     *   languageColumn: 'lang',
+     *   in: 'body',
+     *   query: 'query',
+     * });
+     * ```
      *
-     * // returning only `id`
-     * const id = await db.table.find(1).get('id').update({ name: 'new name' });
+     * ## text vector to search in
      *
-     * // `selectAll` + `find` will return a full record
-     * const oneFullRecord = await db.table
-     *   .selectAll()
-     *   .find(1)
-     *   .update({ name: 'new name' });
+     * The text to search in can be a simple string, or a raw SQL, or a text column, or multiple columns:
      *
-     * // `selectAll` + `where` will return array of full records
-     * const recordsArray = await db.table
-     *   .select('id', 'name')
-     *   .where({ id: 1 })
-     *   .update({ name: 'new name' });
+     * ```ts
+     * db.table.search({
+     *   // search in the given string
+     *   text: 'simply a string to search in',
+     *   query: 'query',
+     * });
      *
-     * await db.table.where({ ...conditions }).update({
-     *   // set the column to a specific value
-     *   column1: 123,
+     * import { raw } from 'orchid-orm';
      *
-     *   // use raw SQL to update the column
-     *   column2: db.table.sql`2 + 2`,
+     * db.table.search({
+     *   // raw SQL: join text columns with space
+     *   text: raw`concat_ws(' ', title, body)`,
+     *   query: 'query',
+     * });
      *
-     *   // use query that returns a single value
-     *   // returning multiple values will result in Postgres error
-     *   column3: db.otherTable.get('someColumn'),
+     * db.table.search({
+     *   // search in a single text column
+     *   in: 'body',
+     *   query: 'query',
+     * });
      *
-     *   // select a single value from a related record
-     *   fromRelation: (q) => q.relatedTable.get('someColumn'),
+     * db.table.search({
+     *   // search in multiple columns, they are concatenated with `concat_ws` as shown above
+     *   in: ['title', 'body'],
+     *   query: 'query',
+     * });
      *
-     *   // set a new value to the `.foo.bar` path into a JSON column
-     *   jsonColumn: (q) => q.jsonSet('jsonColumn', ['foo', 'bar'], 'new value'),
+     * db.table.search({
+     *   // search in multiple columns with different weights. Weight can be A, B, C, or D
+     *   in: {
+     *     title: 'A',
+     *     body: 'B',
+     *   },
+     *   query: 'query',
      * });
      * ```
      *
-     * `null` value will set a column to `NULL`, but the `undefined` value will be ignored:
+     * For better performance, define a [generated](/guide/migration-column-methods.html#generated) column of `tsvector` type, and use it in the search with `vector` keyword:
      *
      * ```ts
-     * db.table.findBy({ id: 1 }).update({
-     *   name: null, // updates to null
-     *   age: undefined, // skipped, no effect
+     * db.table.search({
+     *   vector: 'titleAndBodyVector',
+     *   query: 'query',
      * });
      * ```
      *
-     * @param arg - data to update records with, may have specific values, raw SQL, queries, or callbacks with sub-queries.
-     */
-    update<T extends Query>(this: T, arg: UpdateArg<T>): UpdateResult<T>;
-    _update<T extends Query>(this: T, arg: UpdateArg<T>): UpdateResult<T>;
-    /**
-     * `updateRaw` is for updating records with raw expression.
+     * ## search query
      *
-     * The behavior is the same as a regular `update` method has:
-     * `find` or `where` must precede calling this method,
-     * it returns an updated count by default,
-     * you can customize returning data by using `select`.
+     * Read about different search queries in [this Postgres doc](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES).
      *
-     * ```ts
-     * const value = 'new name';
+     * `search` method can accept one of the following queries:
      *
-     * // update with SQL template string
-     * const updatedCount = await db.table.find(1).updateRaw`name = ${value}`;
+     * - `query`: corresponds to `websearch_to_tsquery` in Postgres, good to use by default
+     * - `plainQuery`: corresponds to `plainto_tsquery`
+     * - `phraseQuery`: corresponds to `phraseto_tsquery`
+     * - `tsQuery`: corresponds to `to_tsquery`
      *
-     * // or update with `sql` function:
-     * await db.table.find(1).updateRaw(db.table.sql`name = ${value}`);
-     * ```
-     * @param args - raw SQL via a template string or by using a `sql` method
-     */
-    updateRaw<T extends Query>(this: T, ...args: UpdateRawArgs<T>): UpdateResult<T>;
-    _updateRaw<T extends Query>(this: T, ...args: UpdateRawArgs<T>): UpdateResult<T>;
-    /**
-     * To make sure that at least one row was updated use `updateOrThrow`:
+     * The `query` (`websearch_to_tsquery`) can work with any user input, while other query kinds require a specific format and will fail for invalid input.
      *
-     * ```ts
-     * import { NotFoundError } from 'pqb';
+     * Each query kind accepts a string or a raw SQL.
      *
-     * try {
-     *   // updatedCount is guaranteed to be greater than 0
-     *   const updatedCount = await db.table
-     *     .where(conditions)
-     *     .updateOrThrow({ name: 'name' });
+     * ```ts
+     * import { raw } from 'orchid-orm';
      *
-     *   // updatedRecords is guaranteed to be a non-empty array
-     *   const updatedRecords = await db.table
-     *     .where(conditions)
-     *     .select('id')
-     *     .updateOrThrow({ name: 'name' });
-     * } catch (err) {
-     *   if (err instanceof NotFoundError) {
-     *     // handle error
-     *   }
-     * }
+     * db.table.search({
+     *   vector: 'titleAndBodyVector',
+     *   // can accept raw SQL:
+     *   phraseQuery: raw`'The Fat Rats'`,
+     * });
      * ```
      *
-     * @param arg - data to update records with, may have specific values, raw SQL, queries, or callbacks with sub-queries.
-     */
-    updateOrThrow<T extends Query>(this: T, arg: UpdateArg<T>): UpdateResult<T>;
-    _updateOrThrow<T extends Query>(this: T, arg: UpdateArg<T>): UpdateResult<T>;
-    /**
-     * Increments a column value by the specified amount. Optionally takes `returning` argument.
+     * ## order by search rank
+     *
+     * Read about search ranking in [this Postgres doc](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING).
+     *
+     * Set `order: true` to order results by the search rank:
      *
      * ```ts
-     * // increment numericColumn column by 1, return updated records
-     * const result = await db.table
-     *   .selectAll()
-     *   .where(...conditions)
-     *   .increment('numericColumn');
+     * db.table.search({
+     *   in: 'body',
+     *   query: 'query',
+     *   // will add ORDER BY ts_rank(to_tsvector('english', body)) DESC
+     *   order: true,
+     * });
+     * ```
      *
-     * // increment someColumn by 5 and otherColumn by 10, return updated records
-     * const result2 = await db.table
-     *   .selectAll()
-     *   .where(...conditions)
-     *   .increment({
-     *     someColumn: 5,
-     *     otherColumn: 10,
-     *   });
+     * To order with `ts_rank_cd` instead of `ts_rank`, set `coverDensity: true`:
+     *
+     * ```ts
+     * db.table.search({
+     *   in: 'body',
+     *   query: 'query',
+     *   // will add ORDER BY ts_rank_cd(to_tsvector('english', body)) DESC
+     *   order: {
+     *     coverDensity: true,
+     *   },
+     * });
      * ```
      *
-     * @param data - name of the column to increment, or an object with columns and values to add
-     */
-    increment<T extends Query>(this: T, data: ChangeCountArg<T>): UpdateResult<T>;
-    _increment<T extends Query>(this: T, data: ChangeCountArg<T>): UpdateResult<T>;
-    /**
-     * Decrements a column value by the specified amount. Optionally takes `returning` argument.
+     * Other options are:
      *
      * ```ts
-     * // decrement numericColumn column by 1, return updated records
-     * const result = await db.table
-     *   .selectAll()
-     *   .where(...conditions)
-     *   .decrement('numericColumn');
+     * db.table.search({
+     *   in: 'body',
+     *   query: 'query',
+     *   order: {
+     *     // weights for D, C, B, A:
+     *     weights: [0.1, 0.2, 0.4, 1],
+     *     // by default, rank ignores the document length
+     *     // change rank behavior by providing here a special number
+     *     normalization: 32,
+     *     // it's possible to change the order direction:
+     *     dir: 'ASC', // DESC by default
+     *   },
+     * });
+     * ```
      *
-     * // decrement someColumn by 5 and otherColumn by 10, return updated records
-     * const result2 = await db.table
-     *   .selectAll()
-     *   .where(...conditions)
-     *   .decrement({
-     *     someColumn: 5,
-     *     otherColumn: 10,
+     * Giving the `as` alias for the search allows to set the ordering in the `order` method:
+     *
+     * ```ts
+     * db.table
+     *   .search({
+     *     as: 'search',
+     *     in: 'body',
+     *     query: 'query',
+     *   })
+     *   .order({
+     *     // can be `search: true` for defaults
+     *     search: {
+     *       // same options as above
+     *       coverDensity: true,
+     *       weights: [0.1, 0.2, 0.4, 1.0],
+     *       normalization: 32,
+     *       dir: 'ASC',
+     *     },
      *   });
      * ```
      *
-     * @param data - name of the column to decrement, or an object with columns and values to subtract
+     * @param arg - search config
      */
-    decrement<T extends Query>(this: T, data: ChangeCountArg<T>): UpdateResult<T>;
-    _decrement<T extends Query>(this: T, data: ChangeCountArg<T>): UpdateResult<T>;
-}
-
-type IsolationLevel = 'SERIALIZABLE' | 'REPEATABLE READ' | 'READ COMMITTED' | 'READ UNCOMMITTED';
-type TransactionOptions = {
-    level: IsolationLevel;
-    readOnly?: boolean;
-    deferrable?: boolean;
-};
-declare class Transaction {
-    transaction<T extends Query, Result>(this: T, cb: () => Promise<Result>): Promise<Result>;
-    transaction<T extends Query, Result>(this: T, options: IsolationLevel | TransactionOptions, cb: () => Promise<Result>): Promise<Result>;
+    search<T extends Query, As extends string>(this: T, arg: SearchArg<T, As>): WhereSearchResult<T, As>;
+    _search<T extends Query, As extends string>(this: T, arg: SearchArg<T, As>): WhereSearchResult<T, As>;
 }
 
 type UpsertCreateArg<T extends Query> = CreateData<T> | (() => CreateData<T>);
@@ -4086,37 +4674,46 @@ declare class QueryMethods<CT extends ColumnTypesBase> {
     distinct<T extends Query>(this: T, ...columns: SelectableOrExpression<T>[]): T;
     _distinct<T extends Query>(this: T, ...columns: SelectableOrExpression<T>[]): T;
     /**
-     * Find a single record by the primary key (id), adds `LIMIT 1`.
-     * Throws when not found.
+     * The `find` method is available only for tables which has exactly one primary key.
+     * And also it can accept raw SQL template literal, then the primary key is not required.
+     *
+     * Find record by id, throw [NotFoundError](/guide/error-handling.html) if not found:
      *
      * ```ts
-     * const result: TableType = await db.table.find(123);
+     * await db.table.find(1);
      * ```
      *
-     * @param args - primary key value to find by
+     * ```ts
+     * await db.user.find`
+     *   age = ${age} AND
+     *   name = ${name}
+     * `;
+     * ```
+     *
+     * @param args - primary key value to find by, or a raw SQL
      */
     find<T extends Query>(this: T, ...args: FindArgs<T>): SetQueryReturnsOne<WhereResult<T>>;
     _find<T extends Query>(this: T, ...args: FindArgs<T>): SetQueryReturnsOne<WhereResult<T>>;
     /**
-     * Find a single record by the primary key (id), adds `LIMIT 1`.
+     * Find a single record by the primary key (id), adds `LIMIT 1`, can accept a raw SQL.
      * Returns `undefined` when not found.
      *
      * ```ts
      * const result: TableType | undefined = await db.table.find(123);
      * ```
      *
-     * @param args - primary key value to find by
+     * @param args - primary key value to find by, or a raw SQL
      */
     findOptional<T extends Query>(this: T, ...args: FindArgs<T>): SetQueryReturnsOneOptional<WhereResult<T>>;
     _findOptional<T extends Query>(this: T, ...args: FindArgs<T>): SetQueryReturnsOneOptional<WhereResult<T>>;
     /**
      * The same as `where(conditions).take()`, it will filter records and add a `LIMIT 1`.
-     * Throws when not found.
+     * Throws `NotFoundError` if not found.
      *
      * ```ts
-     * const result: TableType = await db.table.findBy({
-     *   key: 'value',
-     * });
+     * const result: TableType = await db.table.findBy({ key: 'value' });
+     * // is equivalent to:
+     * db.table.where({ key: 'value' }).take()
      * ```
      *
      * @param args - `where` conditions
@@ -4267,6 +4864,15 @@ declare class QueryMethods<CT extends ColumnTypesBase> {
      */
     offset<T extends Query>(this: T, arg: number | undefined): T;
     _offset<T extends Query>(this: T, arg: number | undefined): T;
+    /**
+     * Use `exists()` to check if there is at least one record-matching condition.
+     *
+     * It will discard previous `select` statements if any. Returns a boolean.
+     *
+     * ```ts
+     * const exists: boolean = await db.table.where(...conditions).exists();
+     * ```
+     */
     exists<T extends Query>(this: T): SetQueryReturnsColumn<T, BooleanColumn>;
     _exists<T extends Query>(this: T): SetQueryReturnsColumn<T, BooleanColumn>;
     /**