> 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

## Resource: Query Items

## Article: Query Items

## Article Link: https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/query-items.md

## Article Content:

# Query Items

Use the [Data API](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/about-the-data-api.md) to find, filter, and retrieve items from a site's collections. This article builds queries step by step, from a simple query to queries with filters, sorting, paging, and referenced items.

The examples run in site code, such as a backend extension. They use `await`, so run them inside an `async` function. If the caller doesn't have [permission](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/introduction/about-collections.md#permissions) to read the collection, the query fails.

Call [`items.query()`](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items?apiView=SDK.md) with a collection ID and a request object that describes the filter, sort order, and paging you need. The response includes the matching items and paging information.

## Run a simple query

This example retrieves the items in the `Listings` collection:

```javascript
import { items } from "@wix/data";

const listingResults = await items.query("Listings", {});

console.log("Listings:", listingResults.items);
```

An empty request object, `{}`, returns items with no filter or sort applied. A query returns up to 50 items unless you set a limit. To get more, see [Get more results](#get-more-results).

## Add filters, sorting, and a limit

To refine the results, add `filter`, `sort`, and `paging` to the request object.

This example retrieves up to 20 listings with two or more bedrooms, sorted by price from lowest to highest:

```javascript
import { items } from "@wix/data";

const results = await items.query("Listings", {
  filter: { bedrooms: { $gte: 2 } }, // 2 or more bedrooms
  sort: [{ fieldName: "price", order: "ASC" }], // Lowest price first
  paging: { limit: 20 }, // Return up to 20 items
});

console.log("Listings:", results.items);
```

The `filter` object supports operators such as `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, and `$contains`. A field with no operator, such as `{ status: "available" }`, matches an exact value. For the full request shape, see [Query Data Items](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items?apiView=SDK.md).

## Get more results

A query returns its results one page at a time. The page size is the `paging.limit` you set, which is 50 by default and 1000 at most. Some Wix app collections allow a smaller maximum, such as 100 for `Stores/Products`.

To get the next page, run the query again with `paging.offset` increased by the page size. `pagingMetadata.hasNext` tells you whether there's another page. To get the total number of matching items, pass `{ returnTotalCount: true }` as the query's third argument and read `pagingMetadata.total`.

This example retrieves every listing, 100 at a time:

```javascript
import { items } from "@wix/data";

const allListings = [];
let offset = 0;
let hasNext = true;

while (hasNext) {
  const page = await items.query(
    "Listings",
    { paging: { limit: 100, offset } },
    { returnTotalCount: true }
  );

  allListings.push(...page.items);
  hasNext = page.pagingMetadata.hasNext ?? false;
  offset += 100;
}
```

## Include referenced items

When a collection has a [reference field](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/introduction/about-collection-fields.md#reference-fields), query results don't contain the referenced items. A single-reference field holds only the referenced item's ID, and a multi-reference field is left out of the results. To get the referenced items themselves, specify `includeReferences` as the query's third parameter.

This example retrieves listings together with the agent each listing references:

```javascript
import { items } from "@wix/data";

const results = await items.query(
  "Listings",
  {},
  { includeReferences: [{ field: "agent" }] }
);

results.items.forEach((listing) => {
  console.log(`Listing: ${listing.title}`);
  console.log(`Agent: ${listing.agent?.name ?? "none"}`);
});
```

For an item with many references, or for more control over them, call [`queryReferencedItems()`](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-referenced-data-items?apiView=SDK.md) instead. It retrieves the items that one or more specific items reference in a specific field.

## Try a query in a Wix Data script

To try a query without adding it to the site's code, run it in a script from the **Wix Data** view in the Code tab:

1. In the Studio Two editor, open the **Code** tab.
2. Open the Command Palette: press `Command+Shift+P` on macOS or `Control+Shift+P` on Windows.
3. Select **Wix Data: Write Query**. An empty script opens.
4. Enter the query. In these scripts, the items API is available as `wixData`, with no import. `wixData` exists only in scripts. For example:

   ```javascript
   wixData.query("Listings", {
     filter: { bedrooms: { $gte: 2 } },
     sort: [{ fieldName: "price", order: "ASC" }],
   })
   ```

5. Click the play icon, **Wix Data: Run Query**, at the top right of the script tab. The response opens in a `result.json` tab.

Scripts run only when you run them, and they aren't part of the site's code. Besides `wixData`, scripts can use other parts of the Data API with no import, such as `collections` and `indexes`. A script can contain several statements and use `await`, so you can, for example, get an item and then update it. A query in a script returns up to 50 items unless you set a limit, the same as in site code. To change many items, page through the results, or use a bulk method such as `wixData.bulkRemove()`.

If `result.json` doesn't show the response you expect, check the collection in the CMS dashboard to see whether the script ran.

## See also

- [About the Data API](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/about-the-data-api.md)
- [Manage Items](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/manage-items.md)
- [About Cached Queries](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/about-cached-queries.md)
- [Data Items API](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction?apiView=SDK.md)