> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # QueryDataItems # Package: cms # Namespace: DataItemService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items.md ## Permission Scopes: Read Data Items: SCOPE.DC-DATA.READ ## Introduction Retrieves a list of items, on the basis of the filtering, sorting, and paging preferences you provide. Learn more about [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). --- ## REST API ### Schema ``` Method: queryDataItems Description: Retrieves a list of items, on the basis of the filtering, sorting, and paging preferences you provide. Learn more about [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). URL: https://www.wixapis.com/wix-data/v2/items/query Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: dataCollectionId Method parameters: param name: appOptions | type: appOptions | description: Additional parameters specific to the [Wix app collection](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) you are querying. When querying the Wix Stores [Products collection](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-e-commerce-stores/wix-stores-products-collection-fields.md), pass the following optional parameters: - `includeHiddenProducts`: Whether to include hidden products in the response. Default: `false`. - `includeVariants`: Whether to include product variants in the query. Default: `false`. param name: consistentRead | type: consistentRead | description: Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about [Wix Data and eventual consistency](https://dev.wix.com/api/rest/wix-data/wix-data/eventual-consistency). Default: `false` param name: dataCollectionId | type: dataCollectionId | description: GUID of the collection to query. | required: true param name: includeFieldGroups | type: array | description: Requests conditional fields. Currently used only in App Collections. Please refer to app collection documentation or [collection field definitions](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/get-data-collection.md) for a list of valid values. param name: includeReferencedItems | type: array | description: Properties for which to include referenced items in the query's results. Up to 50 referenced items can be included for each item that matches the query. param name: includeReferences | type: array | description: Fields for which to include referenced items. For each reference field specified, the response includes the full data items being referenced. Use this to retrieve related data in a single call without additional queries. Maximum 100 reference configurations can be specified. - name: field | type: string | description: Field containing references in the item. This field must be configured as a reference or multi-reference field in the collection schema. - name: limit | type: integer | description: Maximum number of referenced items to include for each item. When a reference field contains more items than this limit, only the first items up to the limit are included in the response. If not specified, up to 50 items are included. param name: language | type: language | description: Language to translate result text into, in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. If provided, the result text is returned in the specified language. **Note:** Translation for the specified language must be enabled for the collection in [Wix Multilingual](https://www.wix.com/app-market/wix-multilingual). If not provided, result text is not translated. param name: publishPluginOptions | type: PublishPluginOptions - name: includeDraftItems | type: boolean | description: Whether to include draft items. When `true`, both published and draft items are affected. Default: `false`. param name: query | type: QueryV2 - name: paging | type: Paging | description: Paging options to limit and skip the number of retrieved items. - name: limit | type: integer | description: Number of items to load. - name: offset | type: integer | description: Number of items to skip in the current sort order. - name: filter | type: object | description: Filter object. Learn more about filters in [API Query Language](https://dev.wix.com/docs/rest/articles/get-started/api-query-language.md#filters). - name: sort | type: array | description: Sort object. Learn more about sorting in [API Query Language](https://dev.wix.com/docs/rest/articles/get-started/api-query-language.md#sorting). - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: fields | type: array | description: Fields to include for each retrieved item. Only fields specified in the array are included in the response. If the array is empty, all fields are returned. > **Note:** The `_id` system field is always returned. param name: referencedItemOptions | type: array | description: Options for retrieving referenced items. - name: fieldName | type: string | description: Field containing references in the queried item. - name: limit | type: integer | description: Maximum number of referenced items to include for each queried item. param name: returnTotalCount | type: returnTotalCount | description: Whether to return the total count in the response for a query with offset paging. When `true`, the `pagingMetadata` object in the response contains a `total` field. Default: `false` param name: sortMode | type: SortMode - enum: WIX_QUERY - Use the sorting specified in query.sort. RANDOM - Return randomly sorted results, disregarding query.sort. - name: randomOptions | type: RandomOptions | description: Additional options for random sorting. - name: seed | type: integer | description: Seed for the pseudo-random generator. The same seed always generates the same order. Return type: QueryDataItemsResponse - name: dataItems | type: array | description: Retrieved items. - name: id | type: string | description: Data item GUID. - name: dataCollectionId | type: string | description: GUID of the collection this item belongs to - name: data | type: object | description: Data item contents. Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields: + `_id`: Item GUID. + `_createdDate`: Date and time the item was added to the collection. + `_updatedDate`: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. + `_ownerId`: GUID of the user who created the item. Can be modified with site owner permissions. - name: pagingMetadata | type: PagingMetadataV2 | description: Paging information. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used, `returnTotalCount` is `true` in the request, and `tooManyToCount` is false. - name: tooManyToCount | type: boolean | description: Whether the server failed to calculate the `total` field. - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: prev | type: string | description: Cursor pointing to previous page in the list of results. ``` ### Examples ### Query existing items ```curl curl -X POST \ 'https://www.wixapis.com/wix-data/v2/items/query' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "cities", "query": { "filter": { "state": "California" }, "paging": { "limit": 2 } } }' ``` ### Query existing items with filter, sort, paging, projection and total count calculation ```curl curl -X POST \ 'https://www.wixapis.com/wix-data/v2/items/query' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "cities", "query": { "filter": { "state": "California" }, "sort": [ { "fieldName": "population", "order": "ASC" } ], "paging": { "limit": 2 }, "fields": ["population"] }, "returnTotalCount": true }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.cms.DataItemService.queryDataItems(dataCollectionId, queryRequest, options) Description: Retrieves a list of items, on the basis of the filtering, sorting, and paging preferences you provide. Learn more about [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: dataCollectionId, queryRequest Method parameters: param name: dataCollectionId | type: string | description: GUID of the collection to query. | required: true param name: options | type: WixDataQueryOptions none - name: returnTotalCount | type: boolean | description: Whether to return the total count in the response for a query with offset paging. When `true`, the `pagingMetadata` object in the response contains a `total` field. Default: `false` - name: includeReferences | type: array | description: Fields for which to include referenced items. For each reference field specified, the response includes the full data items being referenced. Use this to retrieve related data in a single call without additional queries. Maximum 100 reference configurations can be specified. - name: field | type: string | description: Field containing references in the item. This field must be configured as a reference or multi-reference field in the collection schema. - name: limit | type: integer | description: Maximum number of referenced items to include for each item. When a reference field contains more items than this limit, only the first items up to the limit are included in the response. If not specified, up to 50 items are included. - name: consistentRead | type: boolean | description: Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about [Wix Data and eventual consistency](https://dev.wix.com/api/rest/wix-data/wix-data/eventual-consistency). Default: `false` - name: language | type: string | description: Language to translate result text into, in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. If provided, the result text is returned in the specified language. **Note:** Translation for the specified language must be enabled for the collection in [Wix Multilingual](https://www.wix.com/app-market/wix-multilingual). If not provided, result text is not translated. - name: suppressHooks | type: boolean | description: Whether to suppress data hooks. When `true`, data hooks typically triggered by this endpoint don't run. **Note:** This option can only be used in code that runs in [the Wix site backend](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/backend-code/about-the-site-backend.md). Default: `false` - name: appOptions | type: object | description: Additional parameters specific to the [Wix app collection](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) you are querying. When querying the Wix Stores [Products collection](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-e-commerce-stores/wix-stores-products-collection-fields.md), pass the following optional parameters: - `includeHiddenProducts`: Whether to include hidden products in the response. Default: `false`. - `includeVariants`: Whether to include product variants in the query. Default: `false`. - name: showDrafts | type: boolean | description: When `true`, operations include draft items. Read operations include draft items in their response, and write operations modify draft items. param name: queryRequest | type: WixDataQueryRequest | required: true - ONE-OF: - required: true - name: paging | type: Paging | description: Paging options to limit and skip the number of retrieved items. - name: limit | type: integer | description: Number of items to load. - name: offset | type: integer | description: Number of items to skip in the current sort order. - name: cursorPaging | type: CursorPaging | description: Cursor pointing to a page of results. Not used in the first request. Subsequent requests use the cursor and ignore `filter` and `sort`. - name: limit | type: integer | description: Number of items to load. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. - name: filter | type: object | description: Filter object. Learn more about filters in [API Query Language](https://dev.wix.com/docs/rest/articles/get-started/api-query-language.md#filters). - name: sort | type: array | description: Sort object. Learn more about sorting in [API Query Language](https://dev.wix.com/docs/rest/articles/get-started/api-query-language.md#sorting). - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: fields | type: array | description: Fields to include for each retrieved item. Only fields specified in the array are included in the response. If the array is empty, all fields are returned. > **Note:** The `_id` system field is always returned. Return type: PROMISE - name: dataItems | type: array | description: Retrieved items. - name: _id | type: string | description: Data item GUID. - name: dataCollectionId | type: string | description: GUID of the collection this item belongs to - name: data | type: object | description: Data item contents. Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields: + `_id`: Item GUID. + `_createdDate`: Date and time the item was added to the collection. + `_updatedDate`: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. + `_ownerId`: GUID of the user who created the item. Can be modified with site owner permissions. - name: pagingMetadata | type: PagingMetadataV2 | description: Paging information. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used, `returnTotalCount` is `true` in the request, and `tooManyToCount` is false. - name: tooManyToCount | type: boolean | description: Whether the server failed to calculate the `total` field. - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: prev | type: string | description: Cursor pointing to previous page in the list of results. ``` ### Examples ### query ```javascript import { items } from '@wix/data'; async function query(dataCollectionId,queryRequest,options) { const response = await items.query(dataCollectionId,queryRequest,options); }; ``` ### query (with elevated permissions) ```javascript import { items } from '@wix/data'; import { auth } from '@wix/essentials'; async function myQueryMethod(dataCollectionId,queryRequest,options) { const elevatedQuery = auth.elevate(items.query); const response = await elevatedQuery(dataCollectionId,queryRequest,options); } ``` ### query (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { items } from '@wix/data'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { items }, // Include the auth strategy and host as relevant }); async function query(dataCollectionId,queryRequest,options) { const response = await myWixClient.items.query(dataCollectionId,queryRequest,options); }; ``` ---