> 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

# SearchDataItems

# Package: cms

# Namespace: DataItemService

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/search-data-items.md

## Permission Scopes:
Read Data Items: SCOPE.DC-DATA.READ

## Introduction

Searches for items in a collection on the basis of the filtering, sorting, searching, and paging preferences you provide.

Learn more about [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).

> **Notes:**
> - You can only search collections [created in the CMS](https://support.wix.com/en/article/cms-formerly-content-manager-creating-a-collection) or with the [Data Collections API](https://dev.wix.com/docs/rest/business-solutions/cms/data-collections/introduction.md). Searching isn't currently supported for [Wix app collections](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections), [external collections](https://dev.wix.com/docs/develop-websites/articles/databases/external-databases/overview/integrating-external-databases-with-your-wix-site.md) or [Wix Blocks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/about-wix-blocks.md).
> - Filtering is only supported for fields explicitly defined in the [data collection structure](https://dev.wix.com/docs/rest/business-solutions/cms/data-collections/introduction.md#data-collections-and-their-structure). Fields not defined in the collection structure cannot be used for filtering.
> - Searching for data items is always [eventually consistent](https://dev.wix.com/docs/rest/business-solutions/cms/eventual-consistency.md).

---

## REST API

### Schema

```
 Method: searchDataItems
 Description: Searches for items in a collection on the basis of the filtering, sorting, searching, and paging preferences you provide.  Learn more about [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).  > **Notes:** > - You can only search collections [created in the CMS](https://support.wix.com/en/article/cms-formerly-content-manager-creating-a-collection) or with the [Data Collections API](https://dev.wix.com/docs/rest/business-solutions/cms/data-collections/introduction.md). Searching isn't currently supported for [Wix app collections](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections), [external collections](https://dev.wix.com/docs/develop-websites/articles/databases/external-databases/overview/integrating-external-databases-with-your-wix-site.md) or [Wix Blocks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/about-wix-blocks.md). > - Filtering is only supported for fields explicitly defined in the [data collection structure](https://dev.wix.com/docs/rest/business-solutions/cms/data-collections/introduction.md#data-collections-and-their-structure). Fields not defined in the collection structure cannot be used for filtering. > - Searching for data items is always [eventually consistent](https://dev.wix.com/docs/rest/business-solutions/cms/eventual-consistency.md).  ### Supported filter operators by field type  Each [field type](https://support.wix.com/en/article/cms-formerly-content-manager-about-your-collection-fields#field-type) supports a specific set of [filter operators](https://dev.wix.com/docs/rest/articles/get-started/api-query-language.md#operators). Using a filter operator that's not supported for a given field type causes the search to fail.  | Field Type | Supported Filter Operators | |------------|----------------------------| | Text, Image, Document, URL, Video, Audio, Time, Reference, [Page Link](https://support.wix.com/en/article/cms-formerly-content-manager-about-your-collection-fields#page-link-fields), [Rich Text](https://dev.wix.com/docs/rest/articles/get-started/rich-text.md), [Rich Content](https://dev.wix.com/docs/ricos/getting-started/introduction.md), Address | `$in`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$isEmpty`, `$startsWith` | | Number, Date, Date and Time | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$exists` | | Boolean | `$eq`, `$ne`, `$exists` | | Array of strings | `$hasSome`, `$hasAll`, `$exists` | | Array, Document Array, Object, Any, Media Gallery | `$exists` |  Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-types-in-wix-data.md).
 URL: https://www.wixapis.com/wix-data/v2/items/search
 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: dataCollectionId | type: dataCollectionId | description: GUID of the collection to search. | required: true
   param name: includeReferences | type: array<includeReferences> | 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: 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: referencedItemOptions | type: array<referencedItemOptions> | description: Options for retrieving referenced items.  Learn more about [using reference fields](https://support.wix.com/en/article/cms-using-reference-fields-to-display-content-from-multiple-collections). 
              - name: fieldName | type: string | description: Field in the retrieved item that contains references. 
              - name: limit | type: integer | description: Maximum number of referenced items to include for each retrieved item. 
   param name: search | type: Search   
    - ONE-OF: 
     - name: paging | type: Paging | description: Options for limiting and skipping 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 this 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<Sorting> | 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. 
        - name: search | type: SearchDetails | description: Text to search in the specified collection. 
           - name: mode | type: Mode | description: Determines how multiple search terms are handled.  Default: `OR`. 
                 - enum:
                 -     OR: Logical **OR** relationship. Any search term must exist for an item to be retrieved.
                 -     AND: Logical **AND** relationship. All search terms must exist for an item to be retrieved.
           - name: expression | type: string | description: Search query. Search terms are separated by whitespace. 
           - name: fuzzy | type: boolean | description: Whether to use fuzzy search to accommodate typos and partial matches.  Default: `false`. 
 Return type: SearchDataItemsResponse
  - name: dataItems | type: array<DataItem> | 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 configuration. 
     - 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

### Search for cities that contain "San Francisco" in any field
```curl
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
    "dataCollectionId": "cities",
    "search": {
        "search": {
            "expression": "Francisco",
            "mode": "AND"
        },
        "paging": {
            "limit": 10
        },
        "fields": ["city", "state", "population"]
    }
}'
```

### Search for California cities containing "Palm" or "Valley", sorted in ascending order by population
```curl
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
    "data_collection_id": "cities",
    "search": {
        "filter": {
            "state": "California"
        },
        "sort": [
            {
                "fieldName": "population",
                "order": "ASC"
            }
        ],
        "search": {
            "expression": "Palm Valley"
        },
        "paging": {
            "limit": 3
        }
    }
}'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.cms.DataItemService.searchDataItems(dataCollectionId, searchRequest, options)
 Description: Searches for items in a collection on the basis of the filtering, sorting, searching, and paging preferences you provide.  Learn more about [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).  > **Notes:** > - You can only search collections [created in the CMS](https://support.wix.com/en/article/cms-formerly-content-manager-creating-a-collection) or with the [Data Collections API](https://dev.wix.com/docs/rest/business-solutions/cms/data-collections/introduction.md). Searching isn't currently supported for [Wix app collections](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections), [external collections](https://dev.wix.com/docs/develop-websites/articles/databases/external-databases/overview/integrating-external-databases-with-your-wix-site.md) or [Wix Blocks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/about-wix-blocks.md). > - Filtering is only supported for fields explicitly defined in the [data collection structure](https://dev.wix.com/docs/rest/business-solutions/cms/data-collections/introduction.md#data-collections-and-their-structure). Fields not defined in the collection structure cannot be used for filtering. > - Searching for data items is always [eventually consistent](https://dev.wix.com/docs/rest/business-solutions/cms/eventual-consistency.md).  ### Supported filter operators by field type  Each [field type](https://support.wix.com/en/article/cms-formerly-content-manager-about-your-collection-fields#field-type) supports a specific set of [filter operators](https://dev.wix.com/docs/rest/articles/get-started/api-query-language.md#operators). Using a filter operator that's not supported for a given field type causes the search to fail.  | Field Type | Supported Filter Operators | |------------|----------------------------| | Text, Image, Document, URL, Video, Audio, Time, Reference, [Page Link](https://support.wix.com/en/article/cms-formerly-content-manager-about-your-collection-fields#page-link-fields), [Rich Text](https://dev.wix.com/docs/rest/articles/get-started/rich-text.md), [Rich Content](https://dev.wix.com/docs/ricos/getting-started/introduction.md), Address | `$in`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$isEmpty`, `$startsWith` | | Number, Date, Date and Time | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$exists` | | Boolean | `$eq`, `$ne`, `$exists` | | Array of strings | `$hasSome`, `$hasAll`, `$exists` | | Array, Document Array, Object, Any, Media Gallery | `$exists` |  Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-types-in-wix-data.md).
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  dataCollectionId, searchRequest
 Method parameters: 
   param name: dataCollectionId | type: string | description: GUID of the collection to search. | required: true
   param name: options | type: WixDataDirectSearchOptions  none 
        - name: language | type: string | description: NOT IMPLEMENTED! 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. If not provided, result text is not translated.  > **Note:** Translation for the specified language must be enabled for the collection in [Wix Multilingual](https://www.wix.com/app-market/wix-multilingual). 
        - name: suppressHooks | type: boolean | description: Whether to suppress data hooks.  When `true`, data hooks typically triggered by this endpoint don't run.  Default: `false`.  > **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). 
        - name: referencedItemOptions | type: array<ReferencedItemOptions> | description: Options for retrieving referenced items.  Learn more about [using reference fields](https://support.wix.com/en/article/cms-using-reference-fields-to-display-content-from-multiple-collections). 
           - name: fieldName | type: string | description: Field in the retrieved item that contains references. 
           - name: limit | type: integer | description: Maximum number of referenced items to include for each retrieved item. 
        - name: includeReferences | type: array<IncludeReference> | 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: showDrafts | type: boolean | description: When `true`, operations include draft items. Read operations include draft items in their response, and write operations modify draft items. 
        - name: appOptions | type: object | description: Options for [querying Wix app collections](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-app-collections/querying-wix-app-collections.md). 
        - name: consistentRead | type: boolean | description: When `true`, reads 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/docs/sdk/backend-modules/data/eventual-consistency.md). 
   param name: searchRequest | type: WixDataSearchRequest   | required: true
    - ONE-OF: - required: true
     - name: paging | type: Paging | description: Options for limiting and skipping 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 this 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<Sorting> | 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. 
        - name: search | type: SearchDetails | description: Text to search in the specified collection. 
           - name: mode | type: Mode | description: Determines how multiple search terms are handled.  Default: `OR`. 
                 - enum:
                 -     OR: Logical **OR** relationship. Any search term must exist for an item to be retrieved.
                 -     AND: Logical **AND** relationship. All search terms must exist for an item to be retrieved.
           - name: expression | type: string | description: Search query. Search terms are separated by whitespace. 
           - name: fuzzy | type: boolean | description: Whether to use fuzzy search to accommodate typos and partial matches.  Default: `false`. 
 Return type: PROMISE<SearchDataItemsResponse>
  - name: dataItems | type: array<DataItem> | 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 configuration. 
     - 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

### search
```javascript
import { items } from '@wix/data';

async function search(dataCollectionId,searchRequest,options) {
  const response = await items.search(dataCollectionId,searchRequest,options);
};
```

### search (with elevated permissions)
```javascript
import { items } from '@wix/data';
import { auth } from '@wix/essentials';

async function mySearchMethod(dataCollectionId,searchRequest,options) {
  const elevatedSearch = auth.elevate(items.search);
  const response = await elevatedSearch(dataCollectionId,searchRequest,options);
}
```

### search (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 search(dataCollectionId,searchRequest,options) {
  const response = await myWixClient.items.search(dataCollectionId,searchRequest,options);
};
```

---