From 2d9b9d4cebffd3cf167c5748d919b534f5514172 Mon Sep 17 00:00:00 2001 From: brandonkelly Date: Sun, 29 Jan 2017 19:14:46 -0800 Subject: [PATCH] Element Queries --- README.md | 1 + en/asset-query-params.md | 60 +++++++ en/category-query-params.md | 50 ++++++ en/element-queries.md | 310 ++++++++++++++++++++++++++++++++ en/entry-query-params.md | 59 ++++++ en/matrix-block-query-params.md | 55 ++++++ en/tag-query-params.md | 49 +++++ en/user-query-params.md | 58 ++++++ 8 files changed, 642 insertions(+) create mode 100644 en/asset-query-params.md create mode 100644 en/category-query-params.md create mode 100644 en/element-queries.md create mode 100644 en/entry-query-params.md create mode 100644 en/matrix-block-query-params.md create mode 100644 en/tag-query-params.md create mode 100644 en/user-query-params.md diff --git a/README.md b/README.md index d69698d..21ab646 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ Craft 3 Documentation - Searching - Sites and Localization - Templates +- [Element Queries](en/element-queries.md) - [Content Migrations](en/content-migrations.md) ## Plugin Development diff --git a/en/asset-query-params.md b/en/asset-query-params.md new file mode 100644 index 0000000..d7f7806 --- /dev/null +++ b/en/asset-query-params.md @@ -0,0 +1,60 @@ +Asset Query Params +================== + +Param | Accepts | Description +------------------- | --------------------------------- | ------------------------------------------------------------------------------ +`addOrderBy` | `string|array|Expression` | Adds additional ORDER BY columns to the query +`addSelect` | `string|array|Expression` | Add more columns to the SELECT part of the query +`ancestorDist` | `int|null` | The maximum number of levels that results may be separated from `ancestorOf` +`ancestorOf` | `int|ElementInterface|null` | The element (or its ID) that results must be an ancestor of +`andWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`archived` | `bool` | Whether to return only archived elements +`asArray` | `bool` | Whether to return each element as an array +`contentTable` | `string|null` | The content table that will be joined by this query +`customFields` | `FieldInterface[]|null` | The fields that may be involved in this query +`dateCreated` | `mixed` | When the resulting elements must have been created +`dateModified` | `mixed` | The Date Modified that the resulting assets must have +`dateUpdated` | `mixed` | When the resulting elements must have been last updated +`descendantDist` | `int|null` | The maximum number of levels that results may be separated from `descendantOf` +`descendantOf` | `int|ElementInterface|null` | The element (or its ID) that results must be a descendant of +`elementType` | `string|null` | The name of the `ElementInterface` class +`enabledForSite` | `bool` | Whether the elements must be enabled for the chosen site +`filename` | `string|string[]|null` | The filename(s) that the resulting assets must have +`fixedOrder` | `bool` | Whether results should be returned in the order specified by `id` +`folderId` | `int|int[]|null` | The asset folder ID(s) that the resulting assets must be in +`height` | `int|null` | The height (in pixels) that the resulting assets must have +`id` | `int|int[]|false|null` | The element ID(s) +`includeSubfolders` | `bool` | Whether the query should search the subfolders of `folderId` +`indexBy` | `string|callable` | The name of the column by which the query results should be indexed by +`kind` | `string|string[]|null` | The file kind(s) that the resulting assets must be +`level` | `int|null` | The element’s level within the structure +`limit` | `integer` | Maximum number of records to be returned +`nextSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the next sibling of +`offset` | `integer` | Zero-based offset from where the records are to be returned +`orWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`orderBy` | `array` | How to sort the query results +`positionedAfter` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned after +`positionedBefore` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned before +`prevSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the previous sibling of +`ref` | `string|string[]|null` | The reference code(s) used to identify the element(s) +`relatedTo` | `int|array|ElementInterface|null` | The element relation criteria +`search` | `string|array|SearchQuery|null` | The search term to filter the resulting elements by +`select` | `array` | The columns being selected +`siblingOf` | `int|ElementInterface|null` | The element (or its ID) that the results must be a sibling of +`site` | `string|Site` | Sets the `siteId` param based on a given site(s)’s handle +`siteId` | `int|null` | The site ID that the elements should be returned in +`size` | `int|null` | The size (in bytes) that the resulting assets must have +`slug` | `string|string[]|null` | The slug that resulting elements must have +`source` | `string|string[]|Volume` | Sets the `volumeId` param based on a given volume(s)’s handle(s) +`sourceId` | `int|int[]` | Sets the `volumeId` param +`status` | `string|string[]|null` | The status(es) that the resulting elements must have +`structureId` | `int|false|null` | The structure ID that should be used to join in the structureelements table +`title` | `string|string[]|null` | The title that resulting elements must have +`uid` | `string|string[]|null` | The element UID(s) +`uri` | `string|string[]|null` | The URI that the resulting element must have +`volume` | `string|string[]|Volume|null` | Sets the `volumeId` param based on a given volume(s)’s handle(s) +`volumeId` | `int|int[]|null` | The volume ID(s) that the resulting assets must be in +`where` | `string|array` | Query condition +`width` | `int|null` | The width (in pixels) that the resulting assets must have +`with` | `string|array|null` | The eager-loading declaration +`withTransforms` | `array|null` | The asset transform indexes that should be eager-loaded, if they exist diff --git a/en/category-query-params.md b/en/category-query-params.md new file mode 100644 index 0000000..63d6543 --- /dev/null +++ b/en/category-query-params.md @@ -0,0 +1,50 @@ +Category Query Params +===================== + +Param | Accepts | Description +------------------ | ------------------------------------ | ------------------------------------------------------------------------------ +`addOrderBy` | `string|array|Expression` | Adds additional ORDER BY columns to the query +`addSelect` | `string|array|Expression` | Add more columns to the SELECT part of the query +`ancestorDist` | `int|null` | The maximum number of levels that results may be separated from `ancestorOf` +`ancestorOf` | `int|ElementInterface|null` | The element (or its ID) that results must be an ancestor of +`andWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`archived` | `bool` | Whether to return only archived elements +`asArray` | `bool` | Whether to return each element as an array +`contentTable` | `string|null` | The content table that will be joined by this query +`customFields` | `FieldInterface[]|null` | The fields that may be involved in this query +`dateCreated` | `mixed` | When the resulting elements must have been created +`dateUpdated` | `mixed` | When the resulting elements must have been last updated +`descendantDist` | `int|null` | The maximum number of levels that results may be separated from `descendantOf` +`descendantOf` | `int|ElementInterface|null` | The element (or its ID) that results must be a descendant of +`editable` | `bool` | Whether to only return categories that the user has permission to edit +`elementType` | `string|null` | The name of the `ElementInterface` class +`enabledForSite` | `bool` | Whether the elements must be enabled for the chosen site +`fixedOrder` | `bool` | Whether results should be returned in the order specified by `id` +`group` | `string|string[]|CategoryGroup|null` | Sets the `groupId` param based on a given category group(s)’s handle(s) +`groupId` | `int|int[]|null` | The category group ID(s) that the resulting categories must be in +`id` | `int|int[]|false|null` | The element ID(s) +`indexBy` | `string|callable` | The name of the column by which the query results should be indexed by +`level` | `int|null` | The element’s level within the structure +`limit` | `integer` | Maximum number of records to be returned +`nextSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the next sibling of +`offset` | `integer` | Zero-based offset from where the records are to be returned +`orWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`orderBy` | `array` | How to sort the query results +`positionedAfter` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned after +`positionedBefore` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned before +`prevSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the previous sibling of +`ref` | `string|string[]|null` | The reference code(s) used to identify the element(s) +`relatedTo` | `int|array|ElementInterface|null` | The element relation criteria +`search` | `string|array|SearchQuery|null` | The search term to filter the resulting elements by +`select` | `array` | The columns being selected +`siblingOf` | `int|ElementInterface|null` | The element (or its ID) that the results must be a sibling of +`site` | `string|Site` | Sets the `siteId` param based on a given site(s)’s handle +`siteId` | `int|null` | The site ID that the elements should be returned in +`slug` | `string|string[]|null` | The slug that resulting elements must have +`status` | `string|string[]|null` | The status(es) that the resulting elements must have +`structureId` | `int|false|null` | The structure ID that should be used to join in the structureelements table +`title` | `string|string[]|null` | The title that resulting elements must have +`uid` | `string|string[]|null` | The element UID(s) +`uri` | `string|string[]|null` | The URI that the resulting element must have +`where` | `string|array` | Query condition +`with` | `string|array|null` | The eager-loading declaration diff --git a/en/element-queries.md b/en/element-queries.md new file mode 100644 index 0000000..2b40229 --- /dev/null +++ b/en/element-queries.md @@ -0,0 +1,310 @@ +Element Queries +=============== + +Element queries are [query builders](http://www.yiiframework.com/doc-2.0/guide-db-query-builder.html) that are tuned for fetching elements in Craft. They have several custom parameters, and they abstract away all the complexities of the actual SQL query needed to fetch the elements. Rather than raw data, they return element models. + +## Creating Element Queries + +You can create element queries in both PHP and Twig code. Here’s how: + +Element Type | PHP | Twig +------------- | ------------------------------------ | ---------------------- +Assets | `craft\elements\Asset::find()` | `craft.assets()` +Categories | `craft\elements\Category::find()` | `craft.categories()` +Entries | `craft\elements\Entry::find()` | `craft.entries()` +Matrix blocks | `craft\elements\MatrixBlock::find()` | `craft.matrixBlocks()` +Tags | `craft\elements\Tag::find()` | `craft.tags()` +Users | `craft\elements\User::find()` | `craft.users()` + +## Setting Parameters + +Once you’ve created an element query, you can set parameters on it. + +The available parameters varies by element type. Here are the lists of parameters supported by Craft’s built-in element types: + +- [Assets](asset-query-params.md) +- [Categories](category-query-params.md) +- [Entries](entry-query-params.md) +- [Matrix blocks](matrix-block-query-params.md) +- [Tags](tag-query-params.md) +- [Users](user-query-params.md) + +The parameters should be set with chained method calls, like so: + +#### PHP + +```php +use craft\elements\Entry; + +$query = Entry::find() + ->section('news') + ->limit(10); +``` + +#### Twig + +```twig +{% set query = craft.entries() + .section('news') + .limit(10) %} +``` + +### Batch-Setting Parameters + +You can also batch-set parameters like so: + +#### PHP + +```php +use craft\elements\Entry; + +$query = Entry::find(); +Craft::configure($query, [ + 'section' => 'news', + 'limit' => 10 +]); +``` + +#### Twig + +```twig +{% set query = craft.entries({ + section: 'news', + limit: 10 +}) %} +``` + +## Executing Element Queries + +Once you’ve defined your parameters on the query, there are multiple methods available to execute it, depending on the data you need back. + +### `exists()` + +Returns whether any elements match the query. + +#### PHP + +```php +use craft\elements\Entry; + +$exists = Entry::find() + ->section('news') + ->slug('hello-world') + ->exists(); +``` + +#### Twig + +```twig +{% set exists = craft.entries() + .section('news') + .slug('hello-world') + .exists() %} +``` + +### `count()` + +Returns the total number of elements that are matched by the query. + +#### PHP + +```php +use craft\elements\Entry; + +$count = Entry::find() + ->section('news') + ->count(); +``` + +#### Twig + +```twig +{% set count = craft.entries() + .section('news') + .count() %} +``` + +### `all()` + +Returns all of the elements in an array. + +> {note} If the `asArray` param was set to `true`, then the elements will be represented as raw arrays, rather than element objects. + +#### PHP + +```php +use craft\elements\Entry; + +$entries = Entry::find() + ->section('news') + ->limit(10) + ->all(); +``` + +#### Twig + +```twig +{% set entries = craft.entries() + .section('news') + .limit(10) + .all() %} +``` + +> {tip} If you loop through an element query as if it were an array, `all()` will be called automatically for you, and you will actually be looping through its results. + +### `one()` + +Returns the first matching element, or `null` if there isn’t one. + +> {note} If the `asArray` param was set to `true`, then the element will be represented as a raw array, rather than an element object. + +#### PHP + +```php +use craft\elements\Entry; + +$entry = Entry::find() + ->section('news') + ->slug('hello-world') + ->one(); +``` + +#### Twig + +```twig +{% set entry = craft.entries() + .section('news') + .slug('hello-world') + .one() %} +``` + +### `nth()` + +Returns the `n`th matching element, or `null` if there isn’t one. Note that `n` is 0-indexed, so `nth(0)` will give you the first element, `nth(1)` will give you the second, etc. + +> {note} If the `asArray` param was set to `true`, then the element will be represented as a raw array, rather than an element object. + +#### PHP + +```php +use craft\elements\Entry; + +$entry = Entry::find() + ->section('news') + ->nth(4); +``` + +#### Twig + +```twig +{% set entry = craft.entries() + .section('news') + .nth(4) %} +``` + +### `ids()` + +Returns an array of the IDs of the matching elements. + +#### PHP + +```php +use craft\elements\Entry; + +$entryIds = Entry::find() + ->section('news') + ->ids(); +``` + +#### Twig + +```twig +{% set entryIds = craft.entries() + .section('news') + .ids() %} +``` + +### `column()` + +Returns an array of all the first column’s values. + +> {note} By default the first column will be the elements’ IDs, but you can customize that with the `select()` param. + +#### PHP + +```php +use craft\elements\Entry; + +$uris = Entry::find() + ->section('news') + ->select('uri') + ->column(); +``` + +#### Twig + +```twig +{% set uris = craft.entries() + .section('news') + .select('uri') + .column() %} +``` + +### `scalar()` + +Returns the first column’s value of the first matching element. + +> {note} By default the first column will be the element’s ID, but you can customize that with the `select()` param. + +#### PHP + +```php +use craft\elements\Entry; + +$uri = Entry::find() + ->section('news') + ->slug('hello-world') + ->select('uri') + ->scalar(); +``` + +#### Twig + +```twig +{% set uri = craft.entries() + .section('news') + .slug('hello-world') + .select('uri') + .scalar() %} +``` + +### Aggregate Methods + +The following methods will run an aggregate method on the first column of matching elements, and return the result: + +- `sum()` – Returns the sum of all the values in the first column +- `average()` – Returns the average number of all the values in the first column +- `min()` – Returns the minimum number of all the values in the first column +- `max()` – Returns the maximum number of all the values in the first column + +> {note} By default the first column will be the elements’ IDs, but you can customize that with the `select()` param. + +#### PHP + +```php +use craft\elements\Entry; + +$sum = Entry::find() + ->section('news') + ->select('field_someNumberField') + ->sum(); +``` + +#### Twig + +```twig +{% set sum = craft.entries() + .section('news') + .select('field_someNumberField') + .sum() %} +``` diff --git a/en/entry-query-params.md b/en/entry-query-params.md new file mode 100644 index 0000000..a164fbc --- /dev/null +++ b/en/entry-query-params.md @@ -0,0 +1,59 @@ +Entry Query Params +================== + +Param | Accepts | Description +------------------ | --------------------------------- | ----------------------------------------------------------------------------------------- +`addOrderBy` | `string|array|Expression` | Adds additional ORDER BY columns to the query +`addSelect` | `string|array|Expression` | Add more columns to the SELECT part of the query +`after` | `DateTime|string` | Sets the `postDate` param to only allow entries whose Post Date is after the given value +`ancestorDist` | `int|null` | The maximum number of levels that results may be separated from `ancestorOf` +`ancestorOf` | `int|ElementInterface|null` | The element (or its ID) that results must be an ancestor of +`andWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`archived` | `bool` | Whether to return only archived elements +`asArray` | `bool` | Whether to return each element as an array +`authorGroup` | `string|string[]|null` | Sets the `authorGroupId` param based on a given user group(s)’s handle(s) +`authorGroupId` | `int|int[]|null` | The user group ID(s) that the resulting entries’ authors must be in +`authorId` | `int|int[]|null` | The user ID(s) that the resulting entries’ authors must have +`before` | `DateTime|string` | Sets the `postDate` param to only allow entries whose Post Date is before the given value +`contentTable` | `string|null` | The content table that will be joined by this query +`customFields` | `FieldInterface[]|null` | The fields that may be involved in this query +`dateCreated` | `mixed` | When the resulting elements must have been created +`dateUpdated` | `mixed` | When the resulting elements must have been last updated +`descendantDist` | `int|null` | The maximum number of levels that results may be separated from `descendantOf` +`descendantOf` | `int|ElementInterface|null` | The element (or its ID) that results must be a descendant of +`editable` | `bool` | Whether to only return entries that the user has permission to edit +`elementType` | `string|null` | The name of the `ElementInterface` class +`enabledForSite` | `bool` | Whether the elements must be enabled for the chosen site +`expiryDate` | `mixed` | The Expiry Date that the resulting entries must have +`fixedOrder` | `bool` | Whether results should be returned in the order specified by `id` +`id` | `int|int[]|false|null` | The element ID(s) +`indexBy` | `string|callable` | The name of the column by which the query results should be indexed by +`level` | `int|null` | The element’s level within the structure +`limit` | `integer` | Maximum number of records to be returned +`nextSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the next sibling of +`offset` | `integer` | Zero-based offset from where the records are to be returned +`orWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`orderBy` | `array` | How to sort the query results +`positionedAfter` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned after +`positionedBefore` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned before +`postDate` | `mixed` | The Post Date that the resulting entries must have +`prevSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the previous sibling of +`ref` | `string|string[]|null` | The reference code(s) used to identify the element(s) +`relatedTo` | `int|array|ElementInterface|null` | The element relation criteria +`search` | `string|array|SearchQuery|null` | The search term to filter the resulting elements by +`section` | `string|string[]|Section|null` | Sets the `sectionId` param based on a given section(s)’s handle(s) +`sectionId` | `int|int[]|null` | The section ID(s) that the resulting entries must be in +`select` | `array` | The columns being selected +`siblingOf` | `int|ElementInterface|null` | The element (or its ID) that the results must be a sibling of +`site` | `string|Site` | Sets the `siteId` param based on a given site(s)’s handle +`siteId` | `int|null` | The site ID that the elements should be returned in +`slug` | `string|string[]|null` | The slug that resulting elements must have +`status` | `string|string[]|null` | The status(es) that the resulting elements must have +`structureId` | `int|false|null` | The structure ID that should be used to join in the structureelements table +`title` | `string|string[]|null` | The title that resulting elements must have +`type` | `string|string[]|EntryType|null` | Sets the `typeId` param based on a given entry type(s)’s handle(s) +`typeId` | `int|int[]|null` | The entry type ID(s) that the resulting entries must have +`uid` | `string|string[]|null` | The element UID(s) +`uri` | `string|string[]|null` | The URI that the resulting element must have +`where` | `string|array` | Query condition +`with` | `string|array|null` | The eager-loading declaration diff --git a/en/matrix-block-query-params.md b/en/matrix-block-query-params.md new file mode 100644 index 0000000..6d36622 --- /dev/null +++ b/en/matrix-block-query-params.md @@ -0,0 +1,55 @@ +Matrix Block Query Params +========================= + +Param | Accepts | Description +------------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- +`addOrderBy` | `string|array|Expression` | Adds additional ORDER BY columns to the query +`addSelect` | `string|array|Expression` | Add more columns to the SELECT part of the query +`ancestorDist` | `int|null` | The maximum number of levels that results may be separated from `ancestorOf` +`ancestorOf` | `int|ElementInterface|null` | The element (or its ID) that results must be an ancestor of +`andWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`archived` | `bool` | Whether to return only archived elements +`asArray` | `bool` | Whether to return each element as an array +`contentTable` | `string|null` | The content table that will be joined by this query +`customFields` | `FieldInterface[]|null` | The fields that may be involved in this query +`dateCreated` | `mixed` | When the resulting elements must have been created +`dateUpdated` | `mixed` | When the resulting elements must have been last updated +`descendantDist` | `int|null` | The maximum number of levels that results may be separated from `descendantOf` +`descendantOf` | `int|ElementInterface|null` | The element (or its ID) that results must be a descendant of +`elementType` | `string|null` | The name of the `ElementInterface` class +`enabledForSite` | `bool` | Whether the elements must be enabled for the chosen site +`fieldId` | `int|int[]|string|false|null` | The field ID(s) that the resulting Matrix blocks must belong to +`fixedOrder` | `bool` | Whether results should be returned in the order specified by `id` +`id` | `int|int[]|false|null` | The element ID(s) +`indexBy` | `string|callable` | The name of the column by which the query results should be indexed by +`level` | `int|null` | The element’s level within the structure +`limit` | `integer` | Maximum number of records to be returned +`nextSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the next sibling of +`offset` | `integer` | Zero-based offset from where the records are to be returned +`orWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`orderBy` | `array` | How to sort the query results +`owner` | `ElementInterface` | Sets the `ownerId` and `ownerSiteId` params based on a given element +`ownerId` | `int|int[]|null` | The owner element ID(s) that the resulting Matrix blocks must belong to +`ownerLocale` | `string|string[]` | Sets the `ownerLocale` param +`ownerSite` | `string|string[]|Site` | Sets the `ownerSiteId` param based on a given site(s)’s handle(s) +`ownerSiteId` | `int|string|null` | The site ID that the resulting Matrix blocks must have been defined in, or ':empty:' to find blocks without an owner site ID +`positionedAfter` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned after +`positionedBefore` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned before +`prevSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the previous sibling of +`ref` | `string|string[]|null` | The reference code(s) used to identify the element(s) +`relatedTo` | `int|array|ElementInterface|null` | The element relation criteria +`search` | `string|array|SearchQuery|null` | The search term to filter the resulting elements by +`select` | `array` | The columns being selected +`siblingOf` | `int|ElementInterface|null` | The element (or its ID) that the results must be a sibling of +`site` | `string|Site` | Sets the `siteId` param based on a given site(s)’s handle +`siteId` | `int|null` | The site ID that the elements should be returned in +`slug` | `string|string[]|null` | The slug that resulting elements must have +`status` | `string|string[]|null` | The status(es) that the resulting elements must have +`structureId` | `int|false|null` | The structure ID that should be used to join in the structureelements table +`title` | `string|string[]|null` | The title that resulting elements must have +`type` | `string|string[]|MatrixBlockType|null` | Sets the `typeId` param based on a given block type(s)’s handle(s) +`typeId` | `int|int[]|null` | The block type ID(s) that the resulting Matrix blocks must have +`uid` | `string|string[]|null` | The element UID(s) +`uri` | `string|string[]|null` | The URI that the resulting element must have +`where` | `string|array` | Query condition +`with` | `string|array|null` | The eager-loading declaration diff --git a/en/tag-query-params.md b/en/tag-query-params.md new file mode 100644 index 0000000..289a088 --- /dev/null +++ b/en/tag-query-params.md @@ -0,0 +1,49 @@ +Tag Query Params +================ + +Param | Accepts | Description +------------------ | --------------------------------- | ------------------------------------------------------------------------------ +`addOrderBy` | `string|array|Expression` | Adds additional ORDER BY columns to the query +`addSelect` | `string|array|Expression` | Add more columns to the SELECT part of the query +`ancestorDist` | `int|null` | The maximum number of levels that results may be separated from `ancestorOf` +`ancestorOf` | `int|ElementInterface|null` | The element (or its ID) that results must be an ancestor of +`andWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`archived` | `bool` | Whether to return only archived elements +`asArray` | `bool` | Whether to return each element as an array +`contentTable` | `string|null` | The content table that will be joined by this query +`customFields` | `FieldInterface[]|null` | The fields that may be involved in this query +`dateCreated` | `mixed` | When the resulting elements must have been created +`dateUpdated` | `mixed` | When the resulting elements must have been last updated +`descendantDist` | `int|null` | The maximum number of levels that results may be separated from `descendantOf` +`descendantOf` | `int|ElementInterface|null` | The element (or its ID) that results must be a descendant of +`elementType` | `string|null` | The name of the `ElementInterface` class +`enabledForSite` | `bool` | Whether the elements must be enabled for the chosen site +`fixedOrder` | `bool` | Whether results should be returned in the order specified by `id` +`group` | `string|string[]|TagGroup|null` | Sets the `groupId` param based on a given tag group(s)’s handle(s) +`groupId` | `int|int[]|null` | The tag group ID(s) that the resulting tags must be in +`id` | `int|int[]|false|null` | The element ID(s) +`indexBy` | `string|callable` | The name of the column by which the query results should be indexed by +`level` | `int|null` | The element’s level within the structure +`limit` | `integer` | Maximum number of records to be returned +`nextSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the next sibling of +`offset` | `integer` | Zero-based offset from where the records are to be returned +`orWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`orderBy` | `array` | How to sort the query results +`positionedAfter` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned after +`positionedBefore` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned before +`prevSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the previous sibling of +`ref` | `string|string[]|null` | The reference code(s) used to identify the element(s) +`relatedTo` | `int|array|ElementInterface|null` | The element relation criteria +`search` | `string|array|SearchQuery|null` | The search term to filter the resulting elements by +`select` | `array` | The columns being selected +`siblingOf` | `int|ElementInterface|null` | The element (or its ID) that the results must be a sibling of +`site` | `string|Site` | Sets the `siteId` param based on a given site(s)’s handle +`siteId` | `int|null` | The site ID that the elements should be returned in +`slug` | `string|string[]|null` | The slug that resulting elements must have +`status` | `string|string[]|null` | The status(es) that the resulting elements must have +`structureId` | `int|false|null` | The structure ID that should be used to join in the structureelements table +`title` | `string|string[]|null` | The title that resulting elements must have +`uid` | `string|string[]|null` | The element UID(s) +`uri` | `string|string[]|null` | The URI that the resulting element must have +`where` | `string|array` | Query condition +`with` | `string|array|null` | The eager-loading declaration diff --git a/en/user-query-params.md b/en/user-query-params.md new file mode 100644 index 0000000..529e7b7 --- /dev/null +++ b/en/user-query-params.md @@ -0,0 +1,58 @@ +User Query Params +================= + +Param | Accepts | Description +------------------ | --------------------------------- | ------------------------------------------------------------------------------ +`addOrderBy` | `string|array|Expression` | Adds additional ORDER BY columns to the query +`addSelect` | `string|array|Expression` | Add more columns to the SELECT part of the query +`admin` | `bool` | Whether to only return users that are admins +`ancestorDist` | `int|null` | The maximum number of levels that results may be separated from `ancestorOf` +`ancestorOf` | `int|ElementInterface|null` | The element (or its ID) that results must be an ancestor of +`andWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`archived` | `bool` | Whether to return only archived elements +`asArray` | `bool` | Whether to return each element as an array +`can` | `string|int|false|null` | The permission that the resulting users must have +`client` | `bool` | Whether to only return the client user +`contentTable` | `string|null` | The content table that will be joined by this query +`customFields` | `FieldInterface[]|null` | The fields that may be involved in this query +`dateCreated` | `mixed` | When the resulting elements must have been created +`dateUpdated` | `mixed` | When the resulting elements must have been last updated +`descendantDist` | `int|null` | The maximum number of levels that results may be separated from `descendantOf` +`descendantOf` | `int|ElementInterface|null` | The element (or its ID) that results must be a descendant of +`elementType` | `string|null` | The name of the `ElementInterface` class +`email` | `string|string[]|null` | The email address that the resulting users must have +`enabledForSite` | `bool` | Whether the elements must be enabled for the chosen site +`firstName` | `string|string[]|null` | The first name that the resulting users must have +`fixedOrder` | `bool` | Whether results should be returned in the order specified by `id` +`group` | `string|string[]|UserGroup|null` | Sets the `groupId` param based on a given tag group(s)’s handle(s) +`groupId` | `int|int[]|null` | The tag group ID(s) that the resulting users must be in +`id` | `int|int[]|false|null` | The element ID(s) +`indexBy` | `string|callable` | The name of the column by which the query results should be indexed by +`lastLoginDate` | `mixed` | The date that the resulting entries must have last logged in +`lastName` | `string|string[]|null` | The last name that the resulting users must have +`level` | `int|null` | The element’s level within the structure +`limit` | `integer` | Maximum number of records to be returned +`nextSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the next sibling of +`offset` | `integer` | Zero-based offset from where the records are to be returned +`orWhere` | `string|array` | Adds an additional WHERE condition to the existing one +`orderBy` | `array` | How to sort the query results +`positionedAfter` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned after +`positionedBefore` | `int|ElementInterface|null` | The element (or its ID) that the results must be positioned before +`prevSiblingOf` | `int|ElementInterface|null` | The element (or its ID) that the result must be the previous sibling of +`ref` | `string|string[]|null` | The reference code(s) used to identify the element(s) +`relatedTo` | `int|array|ElementInterface|null` | The element relation criteria +`search` | `string|array|SearchQuery|null` | The search term to filter the resulting elements by +`select` | `array` | The columns being selected +`siblingOf` | `int|ElementInterface|null` | The element (or its ID) that the results must be a sibling of +`site` | `string|Site` | Sets the `siteId` param based on a given site(s)’s handle +`siteId` | `int|null` | The site ID that the elements should be returned in +`slug` | `string|string[]|null` | The slug that resulting elements must have +`status` | `string|string[]|null` | The status(es) that the resulting elements must have +`structureId` | `int|false|null` | The structure ID that should be used to join in the structureelements table +`title` | `string|string[]|null` | The title that resulting elements must have +`uid` | `string|string[]|null` | The element UID(s) +`uri` | `string|string[]|null` | The URI that the resulting element must have +`username` | `string|string[]|null` | The username that the resulting users must have +`where` | `string|array` | Query condition +`with` | `string|array|null` | The eager-loading declaration +`withPassword` | `bool` | Whether the users' passwords should be fetched