Query examples for authoring operations
You can perform authoring operations using queries and mutations for the following GraphQL types:
-
Item
-
Media
-
Search
-
Site
-
Template
For a complete list of available types and operations, refer to the built-in documentation in the GraphQL IDE.
Search criteria
The following sections describe the search criteria you can apply to your queries.
Exact
The search criterion is an exact match of the query term. For example, if you search for "apple", the query will only return results for which the exact value is "apple".
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "_group",
"value": "227473f1dc3f4d3a8558865f49b4f64f",
"criteriaType": "EXACT"
}
]
}
}
}StartsWith
Returns a field value that starts with the specified search criterion. For example, searching for "app" returns both "apple" and "application".
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "_group",
"value": "227473f1dc3f4d3a8558",
"criteriaType": "STARTSWITH"
}
]
}
}
}Contains
Returns a field value that contains the specified search criterion. For example, searching for "app" returns "apple", "application", "happen".
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "_group",
"value": "c3f4d3a8558",
"criteriaType": "CONTAINS"
}
]
}
}
}EndsWith
Returns a field value that ends with the specified search criterion. For example, searching for "ple" returns both "apple" and "maple".
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "_group",
"value": "65f49b4f64f",
"criteriaType": "ENDSWITH"
}
]
}
}
}Wildcard
Includes a wildcard in the search criterion. For example, searching for "a*e" returns both "apple" and "angle".
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "_group",
"value": "227*f64f",
"criteriaType": "WILDCARD"
}
]
}
}
}Search
Searches for a full-text phrase within a value. For example, searching for "apple pie" returns items for which the value is "We made apple pie".
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "_name",
"value": "Unlock",
"criteriaType": "SEARCH"
}
]
}
}
}Range
Searches for a range of values in numerical and date fields. For example, you can search for any value between 1 to 5. When applying this criterion, also enter the value: a string defining the queried range within brackets. When entering the value, note the following:
-
The type of bracket determines whether the range is inclusive or exclusive. Square brackets denote an inclusive range, and round brackets denote an exclusive range. You can mix bracket types in a single query, for example: if the value is
[10 TO 20), 10 is included but 20 is excluded. -
Separate the lowest and highest values with the string
TO(case-sensitive). -
Use an asterisk * to denote an unrestricted value (no lower or upper limit). For example, if the value is
(10 TO *), 10 is excluded, and there is no upper limit.
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "__boost",
"value": "[1 TO 5]",
"criteriaType": "RANGE"
}
]
}
}
}Fuzzy
Used to find matches that are similar to the search term, allowing for minor differences such as typos or variations in spelling. It uses similarity parameters (a value between 0 and 1) to determine how close the match should be to the search term. A higher value means stricter matching. For example, searching for "example" with a similarity parameter of 0.8 might match "exampel" and "exmple".
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "_name",
"value": "secuty",
"criteriaType": "FUZZY",
"parameters": "0.5"
}
]
}
}
}Proximity
Used to find documents where the search terms might be separated from each other by other words. The number of separating words is designated with parameters. For example, searching for "apple pie" with a proximity parameter of 5 returns "apple is not a pie".
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "_name",
"value": "collection",
"criteriaType": "PROXIMITY",
"parameters": "0"
}
]
}
}
}RegEx
A search term that applies a regular expression (RegEx). For example, searching for "a.*e$" returns "apple" and "angle".
{
"model": {
"index": "sitecore_master_index",
"searchStatement": {
"criteria": [
{
"field": "_name",
"value": "\\w*configuration",
"criteriaType": "REGEXP"
}
]
}
}
}Query examples
The following sections contain example queries for authoring operations.
Create an item
You can create an item with the createItem mutation.
Query
mutation {
createItem(
input: {
name: "Sitecore Authoring and Management API"
templateId: "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"
parent: "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
language: "en"
fields: [
{ name: "title", value: "Welcome to Sitecore" }
{ name: "text", value: "Welcome to Sitecore" }
]
}
) {
item {
itemId
name
path
fields(ownFields: true, excludeStandardFields: true) {
nodes {
name
value
}
}
}
}
}Result
{
"data": {
"createItem": {
"item": {
"itemId": "30a8616da7c6411db307d4f2c9684e76",
"name": "Sitecore Authoring and Management API",
"path": "/sitecore/content/Home/Sitecore Authoring and Management API",
"fields": {
"nodes": [
{
"name": "Text",
"value": "Welcome to Sitecore"
},
{
"name": "Title",
"value": "Welcome to Sitecore"
}
]
}
}
}
}
}Delete an item
You can delete an Item using the deleteItem mutation. You can specify the item ID or path. If you specify both, the path parameter is ignored. You can request a permanent deletion by setting the permanently parameter value to true in the request input.
Query
mutation {
deleteItem( input: {
path: "/sitecore/content/Home/Sitecore Authoring and Management API"
permanently: true
}
) {
successful
}
}Result
{
"data": {
"deleteItem": {
"successful": true
}
}
}Get an item
You can use the getItem mutation to retrieve an item.
Query
query {
item(
where: {
database: "master",
itemId: "{A58AAB49-FE07-4GT5-B03F-927C581E74D7}"
}){
itemId
name
path
fields(ownFields: true, excludeStandardFields: true) {
nodes {
name
value
}
}
}
}Result
{
"data": {
"item": {
"itemId": "a58aab49fe074gt5b03f927c581e74d7",
"name": "Sitecore Authoring and Management API",
"path": "/sitecore/content/Home/Sitecore Authoring and Management API",
"fields": {
"nodes": [
{
"name": "Text",
"value": "Welcome to Sitecore"
},
{
"name": "Title",
"value": "Welcome to Sitecore"
}
]
}
}
}
}Create a Template item
You can use the createItemTemplate mutation to create the item template.
Query
mutation {
createItemTemplate(
input: {
name: "NewTemplate"
parent: "{B29EE504-861C-492F-95A3-0D890B6FCA09}"
sections: {
# Create a new template section if the ID is empty, otherwise update the template section
name: "newSection"
fields: [
# Create a new template field if the ID is empty, otherwise update the template field
{ name: "Field 1", type: "Single-Line Text" }
{ name: "Field 2", type: "Rich Text" }
]
}
}
) {
itemTemplate {
name
ownFields {
nodes {
name
type
}
}
}
}
}Result
{
"data": {
"createItemTemplate": {
"itemTemplate": {
"name": "NewTemplate",
"ownFields": {
"nodes": [
{
"name": "Field 1",
"type": "Single-Line Text"
},
{
"name": "Field 2",
"type": "Rich Text"
}
]
}
}
}
}
}Update a Template item and its fields
You can use the updateItemTemplate mutation to update the item template.
Query
mutation {
updateItemTemplate(
input: {
templateId: "{A597BE8E-3DD6-483F-B474-A18AF0560E89}"
name: "UpdatedTemplate"
sections: [
{
# Create a new template section if the ID is empty, otherwise update the template section
templateSectionId: "{C8076CA2-FDDE-423C-A819-B6C7573B3FF2}"
name: "Updated Section 1"
fields: [
{
# Create a new template field if the ID is empty, otherwise update the template field
fieldId: "{59B88198-5C5B-4E64-A051-3D5ADD003884}"
name: "Updated Field 1"
}
{ name: "Create New Field", type: "Single-Line Text" }
]
}
{ name: "Create New Section 2" }
]
}
) {
itemTemplate {
name
ownFields {
nodes {
name
type
}
}
}
}
}Result
{
"data": {
"updateItemTemplate": {
"itemTemplate": {
"name": "UpdatedTemplate",
"ownFields": {
"nodes": [
{
"name": "Updated Field 1",
"type": "Single-Line Text"
},
{
"name": "Field 2",
"type": "Rich Text"
},
{
"name": "Create New Field",
"type": " Single-Line Text "
}
]
}
}
}
}
}Upload media
You can use the uploadMedia mutation to get a pre-signed upload URL. You use the pre-signed upload URL to upload a media file to Sitecore.
Query
mutation
{
# The itemPath parameter should not include the Sitecore media library obsolete path
# The media item name should be included in the itemPath
uploadMedia(input: { itemPath: "Default Website/new media" }) {
presignedUploadUrl
}
}Result
{
"data": {
"uploadMedia": {
"presignedUploadUrl": "https://xmcloudcm.localhost/sitecore/api/v1/authoring/media/upload?token=dFh6hm_yH2DrUppd2v7zAU4kvIHk7CgMsXgg2ieaeQzKCU7v7q_W_L9mBY7wGyPw0"
}
}
}If the query for a pre-signed upload URL returns an error with the message The specified key is not a valid size for this algorithm, check if the GraphQL.UploadMediaOptions.EncryptionKey setting has a value. For example:
<setting name="GraphQL.UploadMediaOptions.EncryptionKey" value="432A462D4A614E64" />If it does not, you must set it.
After you get the pre-signed upload URL from the response, you can send a POST request to upload the media file to Sitecore.
For example, by using the curl client:
curl --request POST "https://<your_server>/sitecore/api/v1/authoring/media/upload?token=dFh6hm_yH2DrUppd2v7zAU4kvIHk7CgMsXgg2ieaeQzKCU7v7q_W_L9mBY7wGyPw0"
--header "Authorization: Bearer <JWT_TOKEN>" --form =@<path_to_your_file>
The response to the request is a JSON-formatted response with the media item ID, Name, and Full path on successful media upload.
Get the configured site
You can query information about a specific site by its name.
Query
query {
site(siteName: "website") {
name
domain
rootPath
startPath
browserTitle
cacheHtml
cacheMedia
enablePreview
}
}Result
{
"data": {
"site": {
"name": "website",
"domain": "extranet",
"rootPath": "/sitecore/content",
"startPath": "/home",
"browserTitle": "Website - Sitecore",
"cacheHtml": true,
"cacheMedia": true,
"enablePreview": true
}
}
}Search items under a specific path
You can search through all the items using the search query. In addition to the example shown, you can use various system fields in your query, such as _name, _template, _templatename.
Query
query {
search(
query: {
index: "sitecore_master_index"
searchStatement: {
criteria: [
{ criteriaType: SEARCH, field: "Title", value: "sample item" }
{
operator: MUST
field: "_path"
value: "110d559fdea542ea9c1c8a5df7e70ef9"
}
]
}
}
)
{
results {
innerItem {
path
field(name: "Title") {
value
}
}
}
}
}Result
{ "data": {
"search": {
"results": [
{
"innerItem": {
"path": "/sitecore/content/Home/Sample Item1",
"field": {
"value": "Sample Item1"
}
}
},
{
"innerItem": {
"path": "/sitecore/content/Home/Sample Item2",
"field": {
"value": "Sample Item2"
}
}
}
]
}
}
}Sort search results by created date
You can sort search results by a field value.
Query
query {
search(
query: {
index: "sitecore_master_index"
sort: { field: "__smallcreateddate", direction: DESCENDING }
searchStatement: {
criteria: [
{
operator: MUST
field: "_template"
value: "76036f5ecbce46d1af0a4143f9b557aa" # Sample Item template ID
}
]
}
}
) {
results {
innerItem {
name
path
field(name: "__Created") {
value
}
}
}
}
}Result
{
"data": {
"search": {
"results": [
{
"innerItem": {
"name": "NewestItem",
"path": "/sitecore/content/Home/NewestItem",
"field": {
"value": "20241114T120709Z"
}
}
},
{
"innerItem": {
"name": "OldItem",
"path": "/sitecore/content/Home/OldItem",
"field": {
"value": "20230512T110132Z"
}
}
}
]
}
}
}Configure search results using paging
By default, the query returns the first ten search results. You can change this by adding paging parameters to your query.
To do so, use the following parameters:
-
pageSize- the number of results per page. -
skip- the number of results to skip. -
pageIndex- the name of the search results page index to return.
Query
query {
search(
query: {
index: "sitecore_master_index"
paging: { pageSize: 3, skip: 0, pageIndex: 0 }
searchStatement: {
criteria: [
{
operator: MUST
field: "_template"
value: "76036f5ecbce46d1af0a4143f9b557aa" # Sample Item template ID
}
]
}
}
) {
results {
innerItem {
name
path
}
}
}
}Results
{
"data": {
"search": {
"results": [
{
"innerItem": {
"name": "One",
"path": "/sitecore/content/Home/One"
}
},
{
"innerItem": {
"name": "Two",
"path": "/sitecore/content/Home/Two"
}
},
{
"innerItem": {
"name": "Three",
"path": "/sitecore/content/Home/Three"
}
}
]
}
}
}