@wix/wix-data-items-common 1.0.52

package/dist/types/api/WixDataQuery.d.ts

@@ -0,0 +1,702 @@
+import { WixDataQueryOptions, WixDataReadOptions } from './types';
+import { WixDataResult } from './WixDataResult';
+import { WixDataFilter } from './WixDataFilter';
+type Comparable = string | number | Date;
+/**
+ * @builder
+ */
+export interface WixDataQuery {
+    /**
+     * Adds a sort to a query or sort, sorting by the specified properties in descending order.
+     *
+     * The `descending()` function refines this query to sort in descending order of the specified properties. If you
+     * specify more than one property, descending() sorts the results in descending order by each property in the order
+     * they are listed.
+     *
+     * You can sort the following types:
+     *
+     * Number: Sorts numerically.
+     * - Date: Sorts by date and time.
+     * - String: Sorts lexicographically, so `"abc"` comes before `"XYZ"`.
+     * - Reference: Compares by the ID of the referenced item as a String.
+     *
+     * If a property contains a number as a String, that value will be sorted alphabetically and not numerically. Items
+     * that do not have a value for the specified sort property are ranked lowest.
+     * @public
+     * @documentationMaturity preview
+     * @param fields - The properties used in the sort.
+     * @requiredField fields
+     * @returns An object representing the refined query.
+     */
+    descending(...fields: string[]): WixDataQuery;
+    descending(fields: string[]): WixDataQuery;
+    descending(...fields: any): WixDataQuery;
+    /**
+     * Adds a sort to a query or sort, sorting by the specified properties in ascending order.
+     *
+     * The `ascending()` function refines this query in ascending order of the specified properties. If you specify more
+     * than one property, ascending() sorts the results in ascending order by each property in the order they are listed.
+     *
+     * You can sort the following types:
+     * - Number: Sorts numerically.
+     * - Date: Sorts by date and time.
+     * - String: Sorts lexicographically, so `"abc"` comes after `"XYZ"`.
+     * - Reference: Compares by the ID of the referenced item as a String.
+     *
+     * If a property contains a number as a String, that value will be sorted alphabetically and not numerically.
+     * Items that do not have a value for the specified sort property are ranked lowest.
+     * @public
+     * @documentationMaturity preview
+     * @param fields - The properties used in the sort.
+     * @requiredField fields
+     * @returns An object representing the refined query.
+     */
+    ascending(...fields: string[]): WixDataQuery;
+    ascending(fields: string[]): WixDataQuery;
+    ascending(...fields: any): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value equals the specified value.
+     *
+     * The `eq()` function refines this query to only
+     * match items where the value of the specified property equals the specified `value`.
+     *
+     * It only matches values of the same type. For example, a number value stored
+     * as a String type does not match the same number stored as a Number type.
+     *
+     * Matching strings with `eq()` is case sensitive, so `"text"` is not equal to `"Text"`.
+     *
+     * If `field` points to a collection field of type Array, `eq()` includes the item
+     * as long as at least one Array element matches the specified `value`.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with `value`.
+     * @requiredField field
+     * @param value - The value to match against.
+     * @requiredField value
+     * @returns An object representing the refined query.
+     */
+    eq(field: string, value: any): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value does not equal the specified value.
+     *
+     * The `ne()` function refines this query to only
+     * match items where the value of the specified property does not equal the specified `value`.
+     *
+     * It only matches values of the same type. For example, a number value stored
+     * as a String type is considered not equal to the same number stored as a Number type.
+     *
+     * Matching strings with `ne()` is case sensitive, so `"text"` is not equal to `"Text"`.
+     *
+     * If the value of the `field` property is an Array, `ne()` includes items
+     * in which none of the elements of the Array match the specified `value`.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with `value`.
+     * @requiredField field
+     * @param value - The value to match against.
+     * @requiredField value
+     * @returns An object representing the refined query.
+     */
+    ne(field: string, value: any): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value is greater than or equal to the specified
+     * value.
+     *
+     * The `ge()` function refines this query to only
+     * match items where the value of the specified property is greater than or
+     * equal to the specified `value`.
+     *
+     * It only matches values of the same type. For example, a number value stored
+     * as a String type does not match the same number stored as a Number type.
+     *
+     * If a property contains a number as a String, that value will be compared
+     * alphabetically and not numerically. Items that do not have a value for the
+     * specified property are ranked lowest.
+     *
+     * The following types of properties can be compared:
+     * - Number: Compares numerically.
+     * - Date: Compares JavaScript Date objects.
+     * - String: Compares lexicographically,
+     *   so `"abc"` is greater than or equal to `"ABC"` (because of the greater than),
+     *   but `"ABC"` is not greater than or equal to `"abc"`.
+     * - Reference: Compares by the ID of the referenced item as a String.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with `value`.
+     * @requiredField field
+     * @param value - The value to match against.
+     * @requiredField value
+     * @returns An object representing the refined query.
+     */
+    ge(field: string, value: Comparable): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value is greater than the specified value.
+     *
+     * The `gt()` function refines this query to only match
+     * items where the value of the specified property is greater than the specified `value`.
+     *
+     * It only matches values of the same type. For example, a number value stored
+     * as a String type does not match the same number stored as a Number type.
+     *
+     * If a property contains a number as a String, that value will be compared
+     * alphabetically and not numerically. Items that do not have a value for the
+     * specified property are ranked lowest.
+     *
+     * The following types of properties can be compared:
+     * - Number: Compares numerically.
+     * - Date: Compares JavaScript Date objects.
+     * - String: Compares lexicographically, so `"text"` is greater than `"Text"`.
+     * - Reference: Compares by the ID of the referenced item as a String.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with `value`.
+     * @requiredField field
+     * @param value - The value to match against.
+     * @requiredField value
+     * @returns An object with the query definition, based on the supplied parameters.
+     */
+    gt(field: string, value: Comparable): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value is less than or equal to the specified
+     * value.
+     *
+     * The `le()` function refines this query to only match
+     * items where the value of the specified property is less than or equal to the
+     * specified `value`.
+     *
+     * It only matches values of the same type. For example, a number value stored
+     * as a String type does not match the same number stored as a Number type.
+     *
+     * If a property contains a number as a String, that value will be compared
+     * alphabetically and not numerically. Items that do not have a value for the
+     * specified property are ranked lowest.
+     *
+     * The following types of properties can be compared:
+     * - Number: Compares numerically.
+     * - Date: Compares JavaScript Date objects.
+     * - String: Compares lexicographically,
+     *   so `"ABC"` is less than or equal to `"abc"` (because of the less than),
+     *   but `"abc"` is not less than or equal to `"ABC"`.
+     * - Reference: Compares by the ID of the referenced item as a String.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with `value`.
+     * @requiredField field
+     * @param value - The value to match against.
+     * @requiredField value
+     * @returns An object representing the refined query.
+     */
+    le(field: string, value: Comparable): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value is less than the specified value.
+     *
+     * The `lt()` function refines this query to only match
+     * items where the value of the specified property is less than the specified `value`.
+     *
+     * It only matches values of the same type. For example, a number value stored
+     * as a String type does not match the same number stored as a Number type.
+     *
+     * If a property contains a number as a String, that value will be compared
+     * alphabetically and not numerically. Items that do not have a value for the
+     * specified property are ranked lowest.
+     *
+     * The following types of properties can be compared:
+     * - Number: Compares numerically.
+     * - Date: Compares JavaScript Date objects.
+     * - String: Compares lexicographically, so `"Text"` is less than `"text"`.
+     * - Reference: Compares by the ID of the referenced item as a String.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with `value`.
+     * @requiredField field
+     * @param value - The value to match against.
+     * @requiredField value
+     * @returns An object with the query definition, based on the supplied parameters.
+     */
+    lt(field: string, value: Comparable): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property has any value.
+     *
+     * The `isNotEmpty()` function refines this query to only match items where the
+     * value of the specified property is not `null` or `undefined`.
+     *
+     * If the property contains any value at all for a given item, including the
+     * empty string or an invalid value, that item will match the query.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property in which to check for a value.
+     * @requiredField field
+     * @returns An object representing the refined query.
+     */
+    isNotEmpty(field: string): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property does not exist or does not have any value.
+     *
+     * The `isEmpty()` function refines this query to only match items where the
+     * value of the specified property is `null` or `undefined` or the property does
+     * not exist.
+     *
+     * If the property contains any value at all for a given item, including the
+     * empty string or an invalid value, that item will match the query.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property in which to check for a value.
+     * @requiredField field
+     * @returns An object representing the refined query.
+     */
+    isEmpty(field: string): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value starts with a specified string.
+     *
+     * The `startsWith()` function refines this query to
+     * only match items where the value of the specified property starts with the
+     * defined `string`. Matching with `startsWith()` is not case sensitive, so `"TEXT"` starts
+     * with `"tex"`.
+     *
+     * You can only use `startsWith()` with a property whose value is a String or Reference.
+     * When using a Reference, `startsWith()` matches by the ID of the referenced item as Strings.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with the `value` parameter.
+     * @requiredField field
+     * @param value - The string to look for at the beginning of the specified property value.
+     * @requiredField value
+     * @returns A `WixDataQuery` object representing the refined query.
+     */
+    startsWith(field: string, value: string): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value ends with a specified string.
+     *
+     * The `endsWith()` function refines this query to only
+     * match items where the value of the specified property ends with the specified
+     * `string`. Matching with `endsWith()` is not case sensitive, so `"TEXT"` ends
+     * with `"ext"`.
+     *
+     * You can only use `endsWith()` with a property whose value is a String or Reference.
+     * When using a Reference, `endsWith()` matches by the ID of the referenced item as Strings.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with the string.
+     * @requiredField field
+     * @param value - The string to look for at the end of the specified property value.
+     * @requiredField value
+     * @returns A `WixDataQuery` object representing the refined query.
+     */
+    endsWith(field: string, value: string): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value contains a specified string.
+     *
+     * The `contains()` function refines this query to
+     * only match items where the value of the specified property contains the
+     * specified `string`. Matching with `contains()` is not case sensitive, so
+     * `"text"` does contain `"Tex"`.
+     *
+     * You can use `contains()` with a property whose value is a String or a Reference.
+     * For properties of type reference it is recommended that you use the [`eq()`](#eq)
+     * function instead of `contains()`. With properties that are References, `contains()`
+     * matches by the ID of the referenced item as a String.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with the string.
+     * @requiredField field
+     * @param value - The string to look for inside the specified property value.
+     * @requiredField value
+     * @returns An object representing the refined query.
+     */
+    contains(field: string, value: string): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value equals any of the specified `values`
+     * parameters.
+     *
+     * The `hasSome()` function refines this query to
+     * only match items where the value of the specified property equals any of
+     * the specified values.
+     *
+     * Matching strings with `hasSome()` is case sensitive, so `"text"` is not equal to `"Text"`.
+     *
+     * If the value of the specified property is an array, `hasSome()` will match
+     * if any of the elements of that array match any of the specified values.
+     *
+     * If the specified property contains multiple references, pass item IDs in the
+     * `value` property. In such a case, `hasSome()` will match if any of the
+     * multiple references match any of the specified ID values.
+     *
+     * You can specify a list of values to match by providing an array of
+     * String, Number, or Date types as the `value` parameters.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with `value`.
+     * @requiredField field
+     * @param values - The values to match against.
+     * @requiredField values
+     * @returns An object representing the refined query.
+     */
+    hasSome(field: string, ...values: Comparable[]): WixDataQuery;
+    /**
+     * Overload for `hasSome()`
+     * @public
+     * @documentationMaturity preview
+     */
+    hasSome(field: string, values: Comparable[]): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property values equals all of the specified `value`
+     * parameters.
+     *
+     * The `hasAll()` function refines this query to
+     * only match items where the value of the specified property equals all of
+     * the specified values.
+     *
+     * Matching strings with `hasAll()` is case sensitive, so `"text"` is not equal to `"Text"`.
+     *
+     * If the value of the specified property is an array, `hasAll()` will match
+     * if there is a match in the elements of that array for all of the specified
+     * values.
+     *
+     * You can specify a list of values to match by providing an array of
+     * String, Number, or Date types as the `value` parameters.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with `value`.
+     * @requiredField field
+     * @param values - The values to match against.
+     * @requiredField values
+     * @returns An object representing the refined query.
+     */
+    hasAll(field: string, ...values: Comparable[]): WixDataQuery;
+    /**
+     * Overload for `hasAll()`
+     * @public
+     * @documentationMaturity preview
+     */
+    hasAll(field: string, values: Comparable[]): WixDataQuery;
+    /**
+     * Adds an `or` condition to the query or filter.
+     *
+     * The `or()` function adds an inclusive `or` condition to this filter. A query or filter
+     * with an `or` returns all the items that match the query or filter as defined up to
+     * the `or` function, the items that match the query or filter passed to the `or`
+     * function, and the items that match both.
+     *
+     * The 'or()' function is designed to work with 2 or more queries or filters.
+     * If you use it on its own, it will return all the items in a collection.
+     * @public
+     * @documentationMaturity preview
+     * @param filter - A filter to add to the initial filter as an `or` condition.
+     * @requiredField filter
+     * @returns An object representing the refined query.
+     */
+    or(filter: WixDataFilter): WixDataQuery;
+    /**
+     * Adds an `and` condition to the query or filter.
+     *
+     * The `and()` function adds an and condition to this query. A query or filter with an `and` returns all the items
+     * that match the query or filter as defined up to the `and` function and also match the query or filter passed to
+     * the `and` function.
+     *
+     * Note that when chaining multiple `WixDataFilter` functions to a query an and condition is assumed. In such cases,
+     * you do not need to add a call to the `and()` function. For example, this query returns results where status is
+     * active **and** age is greater than 25.
+     * ```js
+     * wixClient.items.query("myCollection").eq("status", "active").gt("age", 25);
+     * ```
+     *
+     * The `and()` function is needed when performing compound queries. For example, the final query in this set of
+     * queries returns results where status is either pending or rejected **and** age is either less than 25 or greater
+     * than 65.
+     * ```js
+     * let statusQuery = wixClient.items
+     *   .query("myCollection")
+     *   .eq("status", "pending")
+     *   .or(wixClient.items.filter().eq("status", "rejected"));
+     *
+     * let ageQuery = wixClient.items
+     *   .filter()
+     *   .lt("age", 25)
+     *   .or(wixClient.items.filter().gt("age", 65));
+     *
+     * let statusAndAgeQuery = statusQuery.and(ageQuery);
+     * ```
+     *
+     * The `and()` function is designed to work with 2 or more queries or filters. If you use it on its own, it will
+     * return all the items in a collection.
+     * @public
+     * @documentationMaturity preview
+     * @param filter - A filter to add to the initial query as an `and` condition.
+     * @requiredField filter
+     * @returns An object representing the refined query.
+     */
+    and(filter: WixDataFilter): WixDataQuery;
+    /**
+     * Adds a `not` condition to the query or filter.
+     *
+     * The `not()` function adds a `not` condition to this query. A query with a `not`
+     * returns all the items that match the query as defined up to the `not`
+     * function, but don't match the filter passed to the `not` function.
+     *
+     * If the query only contains a `not()` function, it returns all the items
+     * that don't match the filter defined by the `not` method.
+     *
+     * @public
+     * @documentationMaturity preview
+     * @param filter - A filter to add to the initial filter as a `not` condition.
+     * @requiredField filter
+     * @returns An object representing the refined query.
+     */
+    not(filter: WixDataFilter): WixDataQuery;
+    /**
+     * Refines a query to match items whose specified property value is within a specified range.
+     *
+     * The `between()` function refines this query to only match items where the value of the specified property is
+     * greater than or equal to `rangeStart` and less than `rangeEnd`.
+     *
+     * It only matches values of the same type. For example, a number value stored as a String type does not match the
+     * same number stored as a Number type.
+     *
+     * If a property contains a number as a String, that value will be compared alphabetically and not numerically. Items
+     * that do not have a value for the specified property are ranked lowest.
+     *
+     * The following types of properties can be compared:
+     * - Number: Compares numerically.
+     * - Date: Compares JavaScript Date objects.
+     * - String: Compares lexicographically, so
+     *   - `"A"` and `"M"` are between `"A"` and `"Z"`, but `"a"`, `"m"`, `"z"` and `"Z"` are not.
+     *   - `"A"`, `"M"`, `"Z"`, and `"a"` are between `"A"` and `"z"`, but `"z"` is not.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared with rangeStart and rangeEnd.
+     * @requiredField field
+     * @param rangeStart - The beginning value of the range to match against.
+     * @requiredField rangeStart
+     * @param rangeEnd - The ending value of the range to match against.
+     * @requiredField rangeEnd
+     * @returns An object representing the refined query.
+     */
+    between<T extends Comparable>(field: string, rangeStart: T, rangeEnd: T): WixDataQuery;
+    /**
+     * Returns the number of items that match the query.
+     *
+     * The `count()` function returns a Promise that resolves to the number of
+     * items that match the query. The Promise is rejected if `count()` is called
+     * with incorrect permissions or if any of the functions used to refine the
+     * query is invalid.
+     *
+     * Calling the `count()` function triggers the `beforeCount()` and `afterCount()` hooks if they have been defined.
+     *
+     * Use the `options` parameter to run `count()` without checking for permissions
+     * or without its registered hooks.
+     *
+     * Any function that does not filter query results (e.g., [`ascending()`](#ascending))
+     * does not affect the result of `count()`.
+     *
+     * If you build a query and don't refine it with any `WixDataQuery` functions,
+     * `count()` returns the total number of items in the collection.
+     *
+     * If you have already run a query with `find()`, you can retrieve the number of query results without calling
+     * `count()`.
+     * @public
+     * @documentationMaturity preview
+     * @param options - An object containing options to use when processing this operation.
+     * @returns The number of items that match the query.
+     */
+    count(options?: WixDataReadOptions): Promise<number>;
+    /**
+     * Returns the distinct values that match the query, without duplicates.
+     *
+     * The `distinct()` function returns a Promise that resolves to:
+     * - The distinct values found in the specified field when running the query.
+     * - Additional information about the results, such as the number of values that match the query.
+     *
+     * Unlike `find()`, which returns all item objects that match the query, `distinct()` returns matching field values,
+     * and eliminates duplicate field values from the query result. You cannot use `find()` and `distinct()` together.
+     *
+     * For an item to be resolved as distinct, only the specified field must be distinct. Other fields for that item in
+     * the collection are not evaluated when resolving the promise.
+     *
+     * The Promise is rejected if `distinct()` is called with incorrect permissions or if any of the
+     * functions used to refine the query is invalid.
+     *
+     * >**Note:** Only site visitors with [Data Read](https://support.wix.com/en/article/collection-permissions-an-overview#permissions)
+     * permissions can retrieve and view data. You can override the permissions in backend code by setting the
+     * `suppressAuth` option to `true`.
+     * @public
+     * @documentationMaturity preview
+     * @param field - The property whose value will be compared for distinct values.
+     * @requiredField field
+     * @param options - An object containing options to use when processing this operation.
+     * @returns A Promise that resolves to the results of the query.
+     */
+    distinct(field: string, options?: WixDataQueryOptions): Promise<WixDataResult<any>>;
+    /**
+     * Returns the items that match the query.
+     *
+     * The `find()` function returns a Promise that resolves to the results found
+     * by the query and some information about the results. The Promise is
+     * rejected if `find()` is called with incorrect permissions or if any of the
+     * functions used to refine the query is invalid.
+     *
+     * Calling the `find()` function triggers the `beforeQuery()` and `afterQuery()` hooks if they have been defined.
+     *
+     * > **Note:**
+     * > Calling `find()` triggers hooks for the specified collection only. It doesn't trigger hooks for referenced
+     * > collections.
+     *
+     * Use the `options` parameter to override default preferences:
+     * - Override permission checks with `suppressAuth`.
+     * - Ensure the most up-to-date data is retrieved with `consistentRead`.
+     * - Prevent hooks from running with `suppressHooks`.
+     * - Speed up execution with `omitTotalCount`, if you don't need a count of items matching the query.
+     *
+     * If you build a query and don't refine it with any `wixDataQuery` functions,
+     * `find()` returns the entire collection.
+     * @public
+     * @documentationMaturity preview
+     * @param options - An object containing options to use when processing this operation.
+     * @returns A Promise that resolves to the results of the query.
+     */
+    find(options?: WixDataQueryOptions): Promise<WixDataResult>;
+    /**
+     * Lists the fields to return in a query's results.
+     *
+     * The `fields()` function returns only the specified fields in the query's results.
+     *
+     * You can use `include()` in conjunction with `fields()` to get referenced items.
+     *
+     * When `fields()` receives an empty or invalid property, the query behaves as follows:
+     * - When no fields are specified, the query returns all fields.
+     * - When multiple fields are specified but some are invalid, invalid fields are ignored and valid fields are returned.
+     * - When only invalid fields are specified, only the default `_id` field is returned.
+     * @public
+     * @documentationMaturity preview
+     * @param fields - Properties to return.
+     * @requiredField fields
+     * @returns A `WixDataQuery` object representing the query.
+     */
+    fields(...fields: string[]): WixDataQuery;
+    /**
+     * Limits the number of items the query returns.
+     *
+     * The `limit()` function defines the number of results a query returns in each
+     * page. Only one page of results is retrieved at a time. The `next()`
+     * and `prev()` functions are used to
+     * navigate the pages of a query result.
+     *
+     * By default, `limit` is set to `50`.
+     *
+     * The maximum value that `limit()` can accept is `1000`.
+     *
+     * Note that for some Wix app collections, the maximum value `limit()` can accept is
+     * less than `1000`. For example, the maximum limit for the Wix `Stores/Product` collection is 100.
+     * @public
+     * @documentationMaturity preview
+     * @param limitNumber - The number of items to return, which is also the `pageSize` of the results object.
+     * @requiredField limitNumber
+     * @returns A `WixDataQuery` object representing the refined query.
+     */
+    limit(limitNumber: number): WixDataQuery;
+    /**
+     * Sets the number of items to skip before returning query results.
+     *
+     * The `skip()` function defines the number of results to skip in the query
+     * results before returning new query results.
+     *
+     * For example, if you query a collection and 50 items match your query, but
+     * you set `skip` to 10, the results returned will skip the first 10 items
+     * that match and return the 11th through 50th items.
+     *
+     * By default, `skip` is set to 0.
+     * @public
+     * @documentationMaturity preview
+     * @param skipNumber - The number of items to skip in the query results before returning the results.
+     * @requiredField skipNumber
+     * @returns A `WixDataQuery` object representing the refined query.
+     */
+    skip(skipNumber: number): WixDataQuery;
+    /**
+     * Includes referenced items for the specified properties in a query's results.
+     *
+     * The `include()` function refines a query so that the items returned in the
+     * query's results include the full referenced items for the specified properties.
+     *
+     * For example, suppose you have a **books** collection with an **author**
+     * field that references an **authors** collection. Querying the **books**
+     * collection with an `include("author")` returns the relevant book items
+     * and each item will include the full referenced author item in the book's
+     * `author` property.
+     *
+     * When querying a collection that contains a reference field without using the
+     * `include()` function:
+     * - Single reference field: returned items contain only the ID of the
+     *   referenced item, and not the full referenced items.
+     * - Multiple reference field: returned items do not contain the multiple
+     *   reference field at all.
+     *
+     *  When including a property with multiple references, the following limitations
+     *  apply:
+     *  - Only one property with multiple references can be included.
+     *  - The query will return an error if more than 50 items are returned, regardless
+     *    of any query limit set using the `limit()` function.
+     *  - Each returned item can include up to 50 referenced items. If there are more
+     *    than 50 referenced items, only 50 are returned when the query is run
+     *    and the `partialIncludes`
+     *    property of the returned `WixDataQueryResult`
+     *    is `true`. To retrieve more than 50 referenced items, use the
+     *    `queryReferenced()` function.
+     *
+     * For a discussion of when to use the similar `queryReferenced()`
+     * function and when to use `include()`, see [Querying Items that Reference Other Items](https://support.wix.com/en/article/including-referenced-data-when-filtering).
+     *
+     * > **Notes:**
+     * > - Calling the `include()` function does not trigger any hooks.
+     * > - The `include()` function is not supported for Single Item Collections.
+     * @public
+     * @documentationMaturity preview
+     * @param fieldNames - The properties for which to include referenced items.
+     * @requiredField fieldNames
+     * @returns A `WixDataQuery` object representing the query.
+     */
+    include(...fieldNames: string[]): WixDataQuery;
+    /**
+     * Overload for `include()`
+     * @public
+     * @documentationMaturity preview
+     */
+    include(fieldName: string, limit?: number): WixDataQuery;
+    /**
+     * Overload for `include()`
+     * @public
+     * @documentationMaturity preview
+     */
+    include(fieldName1: string, fieldName2: string, limit?: number): WixDataQuery;
+    /**
+     * Overload for `include()`
+     * @public
+     * @documentationMaturity preview
+     */
+    include(fieldName1: string, fieldName2: string, fieldName3: string, limit?: number): WixDataQuery;
+    /**
+     * Overload for `include()`
+     * @public
+     * @documentationMaturity preview
+     */
+    include(fieldName1: string, fieldName2: string, fieldName3: string, fieldName4: string, limit?: number): WixDataQuery;
+    /**
+     * Overload for `include()`
+     * @public
+     * @documentationMaturity preview
+     */
+    include(fieldName1: string, fieldName2: string, fieldName3: string, fieldName4: string, fieldName5: string, limit?: number): WixDataQuery;
+    /**
+     * Overload for `include()`
+     * @public
+     * @documentationMaturity preview
+     */
+    include(...fieldNamesAndLimit: [...string[], number]): WixDataQuery;
+    /**
+     * Overload for `include()`
+     * @public
+     * @documentationMaturity preview
+     */
+    include(...args: unknown[]): WixDataQuery;
+}
+export {};
+//# sourceMappingURL=WixDataQuery.d.ts.map