Use the Data API 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 to read the collection, the query fails.
Call items.query() 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.
This example retrieves the items in the Listings collection:
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.
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:
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.
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:
When a collection has a reference field, 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:
For an item with many references, or for more control over them, call queryReferencedItems() instead. It retrieves the items that one or more specific items reference in a specific field.
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:
In the Studio Two editor, open the Code tab.
Open the Command Palette: press Command+Shift+P on macOS or Control+Shift+P on Windows.
Select Wix Data: Write Query. An empty script opens.
Enter the query. In these scripts, the items API is available as wixData, with no import. wixData exists only in scripts. For example:
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.
Last updated: 2 November 2026