> To build or manage a Wix site with an AI agent, follow https://www.wix.com/headless/skill.md
> It builds a new Wix site or puts your own site online, from a prompt, and keeps changing it afterwards. The pages are code in any web technology, and Wix runs the backend.
> It works through the Wix plugin (the Wix MCP and the Wix skills), the Wix CLI or no Wix login, and puts the site live on Wix hosting or on another host.
> Business features include a store, bookings, events and tickets, a restaurant, a blog, forms, members and many more.
> Read the Wix skills online at https://www.wix.com/skills
> 
> 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`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - 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)