---
title: Reference - DocumentQuery methods
related:
- https://docs.kentico.com/13/custom-development/working-with-pages-in-the-api.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
This page provides information about the most common and recommended parametrization methods available for the [DocumentQuery API](https://docs.kentico.com/13/custom-development/working-with-pages-in-the-api.md). The methods allow you to parameterize queries, for example to limit which pages are retrieved or specify which page columns are loaded to improve performance.
## Page filtering
| Method | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CheckPermissions | Retrieves pages based on the context of a specific user (the pages are filtered according to the user's permissions). By default, the current user's context is used. _CMSActionContext_ may be used to provide a different user's context.
`
// Retrieves all pages visible to the public user
UserInfo user = UserInfo.Provider.Get("public");
using (new CMSActionContext(user))
{
var pages = new MultiDocumentQuery()
.CheckPermissions();
}
` |
| ExcludePath | Filters the retrieved pages to exclude a website section. See the **Path** parametrization method for general filtering based on included or excluded website sections (page paths).
`
// Retrieves pages from the '/Products' section, including the parent '/Product' page
// Excludes the entire '/Products/Software' sub-section
var pages = new MultiDocumentQuery()
.Path("/Products", PathTypeEnum.Section)
.ExcludePath("/Products/Software", PathTypeEnum.Section);
` |
| FilterDuplicates | Allows filtering of the retrieved data to remove any duplicates caused by [linked pages](https://docs.kentico.com/13/managing-website-content/working-with-pages/copying-and-moving-pages-creating-linked-pages.md).
`
// Retrieves all pages without duplicate (linked) pages
var pages = new MultiDocumentQuery()
.FilterDuplicates();
` |
| InCategories | Selects pages assigned to specific [categories](https://docs.kentico.com/13/managing-website-content/working-with-pages/categorizing-pages/assigning-pages-to-categories.md) _._ To limit the filtering only to pages in enabled categories, use the **InEnabledCategories** method.
To filter pages assigned to site-specific categories, you also need to add the **OnSite** method.
`
// Retrieves all pages that are in the 'Reviews' category
var pages = new MultiDocumentQuery()
.InCategories("Reviews");
` |
| InRelationWith | Retrieves pages that are connected to another page through a [named relationship](https://docs.kentico.com/13/managing-website-content/working-with-pages/working-with-page-relationships.md).
`
// Simulates a page GUID
Guid nodeGuid = Guid.NewGuid();
// Retrieves pages that are in any relationship with a specific page
var pages = new MultiDocumentQuery()
.InRelationWith(nodeGuid);
`
`
// Simulates a page GUID
Guid nodeGuid = Guid.NewGuid();
// Retrieves pages that are in a specified relationship with a specific page
var pages = new MultiDocumentQuery()
.InRelationWith(nodeGuid, "IsRelatedTo");
`
`
// Simulates a page GUID
Guid nodeGuid = Guid.NewGuid();
// Retrieves pages that are on the left side of a specified relationship with a specific page
var pages = new MultiDocumentQuery()
.InRelationWith(nodeGuid, "IsRelatedTo", RelationshipSideEmun.Left);
` |
| MenuItems | Retrieves only pages that are configured by content editors to appear in the website's navigation menus. Specifically, pages must have the _Show in menu_ flag enabled in the Pages application and their page type must have the _Navigation item_ feature enabled.
For more information, see [Building website navigation](https://docs.kentico.com/13/developing-websites/building-website-navigation.md).
`
// Retrieves pages (of all page types) that are configured to appear in navigation menus
var menuItems = new DocumentQuery()
.MenuItems()
// Orders pages according to the content tree
.OrderByAscending("NodeLevel", "NodeOrder")
` |
| NestingLevel | Specifies the relative content tree depth from which pages are retrieved (starting from the root of the retrieved content tree section).
`
// Retrieves one level of child pages under the '/Products' section
var pages = new MultiDocumentQuery()
.Path("/Products", PathTypeEnum.Children)
.NestingLevel(1);
` |
| OnSite | Specifies the site from which the pages are retrieved.
`
// Retrieves all pages from the specified site
var pages = new MultiDocumentQuery()
.OnSite("SampleSite");
` |
| OrderBy\* | Allows ordering of the results based on the value of a specified column.
`
// Retrieves smartphones ordered by their display size
var pages = new DocumentQuery("Custom.Smartphone")
.OrderBy("SmartphoneDisplaySize");
`
`
// Retrieves smartphones based on their display size in descending order
var pages = new DocumentQuery("Custom.Smartphone")
.OrderByDescending("SmartphoneDisplaySize");
` |
| Page | Allows implementation of [pagination](https://en.wikipedia.org/wiki/Pagination) – separating the retrieved data into "pages" of a certain size. Retrieves only the data items that belong within a specific page.
`
// Retrieves the second page of size 5 of all smartphones
var pages = new DocumentQuery("Custom.Smartphone")
.Page(1, 5);
` |
| Path | Specifies the website section from which the pages are retrieved.
`
// Retrieves pages from the '/Products' section including the parent page
var pages = new MultiDocumentQuery()
.Path("/Products", PathTypeEnum.Section);
`
`
// Retrieves child pages from the '/Products' section excluding the parent page
var pages = new MultiDocumentQuery()
.Path("/Products", PathTypeEnum.Children);
` |
| TopN | Specifies the number of records, which are retrieved from the database.
`
// Retrieves top 5 smartphones with the largest display size
var pages = new DocumentQuery("Custom.Smartphone")
.OrderByDescending("SmartphoneDisplaySize")
.TopN(5);
` |
| Where\* | Allows filtering of the pages based on their properties.
`
// Retrieves smartphones whose 'DocumentName' value starts with 'Apple'
var pages = new DocumentQuery("Custom.Smartphone")
.Where("DocumentName", QueryOperator.Like, "Apple%");
`
`
// Retrieves smartphones whose 'DocumentName' starts with 'Apple' or 'BlackBerry'
var pages = new DocumentQuery("Custom.Smartphone")
.Where("DocumentName", QueryOperator.Like, "Apple%")
.Or()
.Where("DocumentName", QueryOperator.Like, "BlackBerry%");
`
`
// Retrieves smartphones whose 'DocumentName' value starts with 'Apple'
var pages = new DocumentQuery("Custom.Smartphone")
.WhereLike("DocumentName", "Apple%");
`
`
// Retrieves smartphones whose 'DocumentName' does NOT start with with 'Apple'
var pages = new DocumentQuery("Custom.Smartphone")
.WhereNotStartsWith("DocumentName", "Apple%");
`**Info:** There are many _Where\*_ conditions [available](https://devnet.kentico.com/docs/13_0/api/html/Methods_T_CMS_DataEngine_WhereCondition.htm). Experiment to find the one that suits your needs. |
| WithTag | Retrieves pages based on the assigned [tags](https://docs.kentico.com/13/managing-website-content/working-with-pages/categorizing-pages/tagging-pages.md).
Note that multiple tags assigned to different tag groups can have identical names. To search for a tag across all tag groups, omit the second method parameter.
`
// Retrieves smartphones that have the 'Android' tag from the 'Smartphones' tag group
var pages = new DocumentQuery("Custom.Smartphone")
.WithTag("Android", "Smartphones");
` |
## Published status
When working with pages under [workflow](https://docs.kentico.com/13/configuring-xperience/configuring-the-environment-for-content-editors/configuring-workflows.md), you may want to retrieve the page version published on the live site in some cases and the latest edited version in others.
| Method | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retrieve the correct version of the page content | |
| LatestVersion | Retrieves the latest edited versions of pages. This parametrization method does not limit the set of retrieved pages, instead, it specifies what version of data is retrieved for pages.
`
// Retrieves the latest edited version of pages
var pages = new MultiDocumentQuery()
.LatestVersion(true);
` |
| PublishedVersion | Retrieves the published versions of pages. This parametrization method does not limit the set of retrieved pages, instead, it specifies what version of page data is retrieved for pages.
`
// Retrieves the published version of pages
var pages = new MultiDocumentQuery()
.PublishedVersion(true);
` |
| Limit the set of retrieved pages | |
| Published | Retrieves pages that are in the published state on the live site (currently set to be published on the live site according to the value of their _Published from_/_Published to_ settings and have a published version). This parametrization method limits the set of retrieved pages but does not ensure that the published version of page data is retrieved.
To retrieve the latest published version of pages as related to workflow and versioning, use the **PublishedVersion** parametrization method.
`
// Retrieves pages that are currently set as published
var pages = new MultiDocumentQuery()
.Published(true);
` |
## Data columns
| Method | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Columns | Specifies the columns of the page which are retrieved.
`
// Retrieves smartphone pages, with only the basic required page columns and a specific column holding operating system data
var pages = new DocumentQuery("Custom.Smartphone")
.Columns("SmartphoneOS");
`**Tip:** **Performance best practice**
Use the _Columns_ method to restrict the amount of data loaded from the database and speed up the querying process.**Info:** When retrieving pages with the _Columns_ query method, the system automatically adds several system columns to the list of retrieved columns. The extra columns are not added to queries where it is not desirable, for example, in queries including DISTINCT or GROUP BY clauses. You can disable the automatic addition of the extra system columns by setting the _Properties.EnsureExtraColumns_ method to false.**Note:** **Updating pages under workflow**
When working with pages under workflow or versioning, use the _Columns_ method only when performing read-only operations. Do not use this method with pages you want to update. The update would likely cause a data loss. |
| WithCoupledColumns | Allows you to access coupled data (i.e., fields of individual page types). This parametrization only needs to be used with _MultiDocumentQuery_, as _DocumentQuery_ loads coupled data by default.
`
// Retrieves pages from the specified section and allows you to access page type fields
var pages = new MultiDocumentQuery()
.Path("/Products/Smartphones")
.WithCoupledColumns();
// Gets the value of the "SmartphoneManufacturer" text field
string manufacturer = pages.FirstOrDefault().GetValue("SmartphoneManufacturer", "Default value");
` |
| WithPageUrlPaths | Retrieves pages together with their URL path data (stored in the _CMS\_PageUrlPath_ database table) on sites that use [content tree-based routing](https://docs.kentico.com/13/developing-websites/implementing-routing/content-tree-based-routing.md). Use this method to reduce the required number of SQL queries if you need to [retrieve the URLs](https://docs.kentico.com/13/developing-websites/retrieving-content/displaying-page-content.md) of the loaded pages, for example when building navigation links.
`
using CMS.DocumentEngine;
using CMS.DocumentEngine.Routing;
...
// Loads pages together with their URL path data for sites using content tree-based routing
var pages = new DocumentQuery().WithPageUrlPaths();
` |
## Culture
| Method | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CombineWithDefaultCulture | Determines whether the default culture version is retrieved for pages that are not available in the selected culture (when used together with the **Culture** parametrization method).
`
// Retrieves the 'sw-se' culture version of pages, or the default culture version if not available
var pages = new MultiDocumentQuery()
.Culture("sw-se");
.CombineWithDefaultCulture();
` |
| CombineWithAnyCulture | Intended for use together with the **Culture** method and multiple culture values. If a page is not available in the first specified culture, the query then attempts to load the next culture in the list. Retrieves the default culture version for pages that are not available for any of the specified cultures.
`
// Retrieves pages in the 'sw-se' culture. Pages unavailable in the 'sw-se' are returned in the 'cs-cz' culture
// Pages unavailable in any of the specified cultures are returned in the site's default culture
var pages = new MultiDocumentQuery()
.Culture("sw-se", "cs-cz")
.CombineWithAnyCulture();
` |
| Culture | Specifies the culture of pages to be retrieved on [multilingual websites](https://docs.kentico.com/13/multilingual-websites.md).
`
// Retrieves all pages that are in the specified culture
var pages = new MultiDocumentQuery()
.Culture("sw-se");
`**Note:** **Using _WithPageUrlPaths_ with the _Columns_ or _Source_ methods**
When using the **WithPageUrlPaths** method together with the **Columns** method or the**Source** [ObjectQuery](https://docs.kentico.com/13/custom-development/retrieving-database-data-using-objectquery-api.md) method, **WithPageUrlPaths** must always be called before the others to prevent corruption of data. |