diff --git a/docs/develop/graphql/index.md b/docs/develop/graphql/index.md index 748a679..37c447d 100644 --- a/docs/develop/graphql/index.md +++ b/docs/develop/graphql/index.md @@ -1,7 +1,3 @@ ---- -status: draft ---- - # GraphQL API [GraphQL](https://graphql.org/) is a data query and manipulation language developed by Facebook. It allows applications to request precisely the data they need, avoiding over-fetching of information. GraphQL offers a flexible and efficient way to access APIs, granting clients control over data retrieval and enabling the bundling of multiple queries into a single request. This makes GraphQL particularly appealing for modern web applications and mobile apps. @@ -26,8 +22,8 @@ Explore the GraphQL API with the interactive [GraphiQL Explorer](getting-started The documentation of the GraphQL API resources is automatically generated based on the GraphQL schema and varies depending on the extensions installed in the IES. Therefore we refer to the interactive GraphiQL explorer which contains the API documentation. - ## Breaking changes + The GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are primarily backward-compatible. Should the GraphQL API change in a way that is not backward compatible, these changes are called "Breaking Changes" and may involve removing or renaming fields, arguments, or other parts of the schema. When a Breaking Change is created, there will be a transition period where the old from will continue to be supported and marked deprecated. Until a time when the parts marked as deprecated are removed. diff --git a/docs/develop/graphql/search/faceted-search.md b/docs/develop/graphql/search/faceted-search.md index 02a431f..01e70fe 100644 --- a/docs/develop/graphql/search/faceted-search.md +++ b/docs/develop/graphql/search/faceted-search.md @@ -1,7 +1,3 @@ ---- -status: draft ---- - # Faceted search A faceted search, also known as faceted filtering, is a search technique that can be applied to various use cases to allow users to easily refine and navigate search results. It works by dividing search results into different categories or facets that are representative features or attributes of the information found. diff --git a/docs/develop/graphql/search/filtered-search.md b/docs/develop/graphql/search/filtered-search.md index db3935f..7dbd8ca 100644 --- a/docs/develop/graphql/search/filtered-search.md +++ b/docs/develop/graphql/search/filtered-search.md @@ -1,7 +1,3 @@ ---- -status: draft ---- - # Filtered search Filters can be used to give the user of the website the possibility to narrow down his search by certain criteria that are offered to him. Filters can also be used to limit the search in general if the results can only be returned from a certain area. The CMS IES recognizes various criteria that can be used for this purpose. diff --git a/docs/develop/graphql/search/index.md b/docs/develop/graphql/search/index.md index c72387a..6a26d25 100644 --- a/docs/develop/graphql/search/index.md +++ b/docs/develop/graphql/search/index.md @@ -1,7 +1,3 @@ ---- -status: draft ---- - # Search The GraphQL query `search` can be used to search for resources. The aim of this GraphQL query is to fulfill the requirements for a search within the website. The focus here is on full-text searches, filters and facets. diff --git a/docs/develop/graphql/search/indexing.md b/docs/develop/graphql/search/indexing.md index b5e93a7..7e1be7a 100644 --- a/docs/develop/graphql/search/indexing.md +++ b/docs/develop/graphql/search/indexing.md @@ -1,7 +1,68 @@ ---- -status: draft ---- - # Indexing Indexing, i.e. filling and updating the search index, is triggered internally and is therefore not publicly accessible. + +## Reindex all documents + +One use case is to recreate the entire index. The mutation [`index`](http://127.0.0.1:8000/develop/graphql/reference/#mutation-rootmutation) is used for this. Without specifying `paths`, the entire index is rebuilt. The field `cleanupThreshold` is also important here, which specifies how many documents must have been successfully indexed so that the old documents are also deleted. This ensures that the index is not emptied if a problem occurs during indexing. + +```graphql +mutation { + index(input: { index: "[client-anchor]-www", cleanupThreshold: 1000 }) { + statusLine + } +} +``` + +There is also a parameter `chunkSize` which can be used to specify how many documents are read in at once in order to index them. In the standard case, this is `500`. If the memory consumption is too high for this, the value can be reduced. Increasing the value no longer provides a performance advantage. + +## Updating individual documents + +If new articles are created or updated in the CMS, they must also be created or updated in the index. This is also done via the mutation [`index`](http://127.0.0.1:8000/develop/graphql/reference/#mutation-rootmutation). However, the paths of the resources that are to be updated must be specified here via the `paths` field. If `paths` is specified, `cleanupThreshold` is not taken into account, as only old versions of the updated documents are deleted. + +```graphql +mutation { + index( + input: { + index: "[client-anchor]-www" + paths: ["news/438237.php", "events/43212.php"] + } + ) { + statusLine + } +} +``` + +There is also a parameter `chunkSize` which can be used to specify how many documents are read in at once in order to index them. In the standard case, this is `500`. If the memory consumption is too high for this, the value can be reduced. Increasing the value no longer provides a performance advantage. + +## Get Indexing status + +Während der Indexer die Dokumente indiziert, kann über die query [`indexerStatus`](http://127.0.0.1:8000/develop/graphql/reference/#query-rootquery) der aktuelle Status abgefragt werden. Z.B. um anzuzeigen wieviele Dokumente bereits indiziert wurde. + +```graphql +{ + indexerStatus(index: "[client-anchor]-www") { + statusLine + } +} +``` + +## Remove documents + +The mutation [`indexRemove`](http://127.0.0.1:8000/develop/graphql/reference/#mutation-rootmutation) is used to remove documents from the index. The corresponding documents are removed from the index by specifying `idList`, which is used to specify a list of resource IDs. + +```graphql +mutation { + indexRemove(index: "[client-anchor]-www", idlist: ["438237", "43212"]) +} +``` + +## Abort indexing + +Das indizieren kann abgebrochen werden. Hierbei wird nach jedem Chunk geprüft, ob der Vorgang abgebrochen werden soll. Über die Mutation [`indexAbort`](http://127.0.0.1:8000/develop/graphql/reference/#mutation-rootmutation) wird dafür gesorgt, das das indizieren unterbrochen wird. + +```graphql +mutation { + indexAbort(index: "[client-anchor]-www") +} +``` diff --git a/docs/develop/graphql/search/resolve-navigation-hierarchy.md b/docs/develop/graphql/search/resolve-navigation-hierarchy.md index 8119e66..0c28099 100644 --- a/docs/develop/graphql/search/resolve-navigation-hierarchy.md +++ b/docs/develop/graphql/search/resolve-navigation-hierarchy.md @@ -1,10 +1,12 @@ ---- -status: draft ---- - # Resolve navigation hierarchy -Root: +Articles can be linked to each other via a hierarchy of any depth. Navigation is a specific type of hierarchy. The navigation field provides a [`Hierarchy`](../reference.md#hierarchy) object that can be used to navigate through the levels. + +The methods of [`Hierarchy`](../reference.md#hierarchy) always return a [`Resource`](../reference.md#resource) object or a list of [`Resource`](../reference.md#resource) objects which can then be used to navigate further in the hierarchy. + +## Get the root + +The `root` field is used to obtain the root of the navigation. ```graphql { @@ -26,7 +28,11 @@ Root: } ``` -Parent: +## Get the parent + +The `parent` field is used to determine the parent resource in the navigation hierarchy. + +The example also shows how the parents are determined over two levels. ```graphql { @@ -53,7 +59,9 @@ Parent: } ``` -Children: +## Get the children + +The subordinate resources in the navigation are queried via the `children` field. ```graphql { @@ -68,9 +76,6 @@ Children: navigation { children { id - teaser { - url - } } } } @@ -78,7 +83,9 @@ Children: } ``` -Path: +## Get the path + +The path describes all higher-level parents up to the root element. The returned list provides the root resource as the first resource, followed by all resources that form the navigation path. The last resource in the list is the resource that should be used to determine the path. ```graphql { diff --git a/docs/develop/graphql/search/resolve-teaser.md b/docs/develop/graphql/search/resolve-teaser.md index 427e801..43d2ce3 100644 --- a/docs/develop/graphql/search/resolve-teaser.md +++ b/docs/develop/graphql/search/resolve-teaser.md @@ -1,12 +1,65 @@ ---- -status: draft ---- - # Resolve teaser +A teaser is a short preview or introduction that serves to arouse the interest of the target group. Typically, a teaser is used to hint at upcoming content, such as an article, news, or event. The purpose of a teaser is to grab people's attention and encourage them to learn more or consume the full content when it is available. Teasers can use text, images, videos or other media formats to pique the curiosity of the target audience. + +Depending on the type of page, a teaser can also be highly customized and contain special data that can only be provided by this type of page. For example, the teaser for a person's page can contain their first and last name and their contact details. + +Due to this property of a teaser, the data cannot be mapped via a single object type. The teaser types listed here cannot be complete, as project-specific teasers can also be defined depending on the project. + +The 'teaser' field is used to determine the teaser of a resource. + +```graphql +{ + search(input: { index: "[client-anchor]-www", text: "movie" }) { + total + offset + queryTime + results { + id + teaser { + __typename + url + } + } + } +} +``` + +In this case, `__typename` and `url` are the only fields that are available for all teaser types. All other fields must be queried individually depending on the teaser type. + +This is solved in GraphQL with [Inline Fragments](https://graphql.org/learn/queries/#inline-fragments). + +```graphql +{ + search(input: { index: "[client-anchor]-www", text: "movie" }) { + total + offset + queryTime + results { + id + teaser { + __typename + url + ... on ArticleTeaser { + headline + text + } + } + } +} +``` + +## ArticleTeaser + +The article teaser is the classic teaser that can contain a headline, a text and possibly an asset (e.g. an image). + +In the following example, the fields of the article teaser are read out and [Fragments](https://graphql.org/learn/queries/#fragments) is also used. + +See also in the [reference](../reference.md#articleteaser). + ```graphql { - search(input: { index: "[client-anchor]-www", text: "Filmabend" }) { + search(input: { index: "[client-anchor]-www", text: "movie" }) { total offset queryTime diff --git a/docs/develop/graphql/search/suggest.md b/docs/develop/graphql/search/suggest.md index 0e88081..a39f89d 100644 --- a/docs/develop/graphql/search/suggest.md +++ b/docs/develop/graphql/search/suggest.md @@ -1,20 +1,58 @@ ---- -status: draft ---- - # Suggest A "suggest search" is a search function that automatically displays suggestions or auto-completions to users as they enter search queries. +A suggest search can be carried out as follows. + +```graphql +{ + suggest(input: { index: "[client-anchor]-www", text: "work" }) { + queryTime + suggestions { + term + hits + } + } +} +``` + +As a result, the suggestions that would lead to hits are returned. The number of hits is indicated with . + +```json +{ + "data": { + "suggest": { + "suggestions": [ + { + "term": "work", + "hits": 32 + }, + { + "term": "workshop", + "hits": 7 + }, + { + "term": "working", + "hits": 5 + }, + ... + ] + } + } +} +``` + +The same [filters](filtered-search.md) can be specified for the suggest search as for a [search](index.md#). The suggest is usually used together with a [full-text search](index.md#full-text-search). In this case, the filters for the search and the suggest should always be the same. This ensures that the suggestions only return the words that lead to hits for the search. + ```graphql { - suggest(input: { - index:"[client-anchor]-www" - text: "holid" - filter: [ - {groups:["1195"]} - ] - }) { + suggest( + input: { + index: "[client-anchor]-www" + text: "holid" + filter: [{ groups: ["1195"] }] + } + ) { queryTime suggestions { term