swagger: '2.0' info: description: | **Search API** Provides access to the search features of Alfresco Content Services. version: '1' title: Alfresco Content Services REST API basePath: /alfresco/api/-default-/public/search/versions/1 securityDefinitions: basicAuth: type: basic description: HTTP Basic Authentication security: - basicAuth: [] consumes: - application/json produces: - application/json paths: '/search': post: x-alfresco-since: "5.2" tags: - search summary: Searches Alfresco description: | **Note**: this endpoint is available in Alfresco 5.2 and newer versions. **You specify all the parameters in this API in a JSON body**, URL parameters are not supported. A basic query looks like this: ```JSON { "query": { "query": "foo" } } ``` **Note:** These are the minimum possible query parameters. The default search language is **afts** ([Alfresco Full Text Search](http://docs.alfresco.com/5.1/concepts/rm-searchsyntax-intro.html)), but you can also specify **cmis**, and **lucene**. A basic CMIS query looks like this: ```JSON { "query": { "query": "select * from cmis:folder", "language": "cmis" } } ``` By default, **results are limited to the first 100.** Results can be restricted using "paging". For example: ```JSON "paging": { "maxItems": "50", "skipCount": "28" } ``` This example would ensure that results are **limited by Final Size**, skipping the first 28 results and returning the next 50. Alternatively, you can limit the results by using the **limits JSON body parameter**. For example, ```JSON "limits": { "permissionEvaluationTime": 20000, "permissionEvaluationCount": 2000 } ``` You can use the **include JSON body parameter** to return additional information. This works in the same way as in the /nodes/{nodeId}/children method in the core API. For example: ```JSON "include": ["aspectNames", "properties", "isLink"] ``` You can use the **fields JSON body parameter** to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. This works in the same way as in the /nodes/{nodeId}/children method in the core API. For example: ```JSON "fields": ["id", "name", "search"] ``` You can sort the results using the **sort JSON body parameter**, for example: ```JSON "sort": [{"type":"FIELD", "field":"cm:description", "ascending":"true"}] ``` **Note:** the **sort** parameter is not supported for CMIS queries. By default, search uses the **"nodes" location**, which is the **content store known as workspace://SpacesStore**. To change the scope to another location you can use the **locations JSON body parameter**. You can specify either **nodes** (the default), **versions** or **deleted-nodes**. For example, ```JSON "scope": { "locations": ["deleted-nodes"] } ``` You can specify templates using the **templates JSON body parameter**, for example: ```JSON "templates": [{"name": "_PERSON","template": "|%firstName OR |%lastName OR |%userName"}, {"name": "mytemplate","template": "%cm:content"}] ``` **Note: Spell checking only works on Search Services (Solr 6) if you have already enabled suggestions.** For **spell checking** you can use a query like this: ```JSON { "query": { "query": "cm:title:alfrezco" }, "spellcheck": {"query": "alfrezco"} } ``` If you are already specifying "userQuery" then the following may be easier and produces the same result : ```JSON { "query": { "query": "cm:title:alfrezco", "userQuery": "alfrezco" }, "spellcheck": {} } ``` The spellcheck response includes a spellCheck context like this: ```JSON "context": { "spellCheck": { "type": "searchInsteadFor", "suggestions": ["alfresco"] } }, ``` To specify defaults, you use a **defaults JSON body parameter**, for example: ```JSON "defaults": { "textAttributes": [ "cm:content", "cm:name" ], "defaultFTSOperator": "AND", "defaultFTSFieldOperator": "OR", "namespace": "cm", "defaultFieldName": "PATH" } ``` You can specify several filter queries using the **filterQueries JSON body parameter**, for example: ```JSON "filterQueries": [{"query": "TYPE:'cm:folder'"},{"query": "cm:creator:mjackson"}] ``` You can specify several facet queries using the **facetQueries JSON body parameter**, for example: ```JSON "facetQueries": [{"query": "created:2016","label": "CreatedThisYear"}] ``` The response will contain a matching "context" section, the "label" will match the facet query. ```JSON "context": { "facetQueries": [ {"label": "CreatedThisYear","count": 3} ] }, ``` A complete query for facetting via the content.size field looks this: ```JSON { "query": { "query": "presentation", "language": "afts" }, "facetQueries": [ {"query": "content.size:[0 TO 10240]", "label": "xtra small"}, {"query": "content.size:[10240 TO 102400]", "label": "small"}, {"query": "content.size:[102400 TO 1048576]", "label": "medium"}, {"query": "content.size:[1048576 TO 16777216]", "label": "large"}, {"query": "content.size:[16777216 TO 134217728]", "label": "xtra large"}, {"query": "content.size:[134217728 TO MAX]", "label": "XX large"} ], "facetFields": {"facets": [{"field": "'content.size'"}]} } ``` The response will contain a matching "context" section, the "label" will match the facet query. ```JSON "context": { "facetQueries": [ { "label": "small","count": 2 }, { "label": "large","count": 0 }, { "label": "xtra small","count": 5 }, { "label": "xtra large","count": 56}, { "label": "medium","count": 4 }, { "label": "XX large", "count": 1 } ] }, ``` You can specify several facet fields using the **facetFields JSON body parameter**, for example: ```JSON "facetFields": {"facets": [{"field": "creator", "mincount": 1}, {"field": "modifier", "mincount": 1}]} ``` The response will contain a matching "context" section, the "label" will match the facet field. ```JSON "context": { "facetsFields": [ { "label": "creator", "buckets": [ { "label": "System", "count": 75 }, { "label": "mjackson", "count": 5 } ]}, { "label": "modifier", "buckets": [ { "label": "System", "count": 72 }, { "label": "mjackson", "count": 5 }, { "label": "admin", "count": 3 } ]} ] }, ``` Grouping facet queries that go together can be done by specifying the group label in the fact queries as follow: ```JSON { "query": { "query": "presentation" }, "facetQueries": [ {"query": "content.size:[0 TO 102400]", "label": "small", "group":"foo"}, {"query": "content.size:[102400 TO 1048576]", "label": "medium","group":"foo"}, {"query": "content.size:[1048576 TO 16777216]", "label": "large","group":"foo"} ] } ``` The above query returns the results a faceted field grouped under the label foo: ```JSON { "context": {"facetsFields": [{ "label": "foo", "buckets": [ { "count": 109, "label": "small", "filterQuery": "content.size:[0 TO 102400]" }, { "count": 0, "label": "large", "filterQuery": "content.size:[1048576 TO 16777216]" }, { "count": 0, "label": "medium", "filterQuery": "content.size:[102400 TO 1048576]" } ] }] } ``` Range Faceting is supported by the **ranges JSON body parameter**, for example: ```JSON { "query": { "query": "presentation" }, "ranges": [ { "field": "content.size", "start": "0", "end": "100", "gap": "20", "hardend": true }, { "field": "created", "start": "2015-09-29T10:45:15.729Z", "end": "2016-09-29T10:45:15.729Z", "gap": "+100DAY" }] } ``` An example query for **search highlighting** could look like this: ```JSON { "query": { "query": "description:workflow", "userQuery":"workflow" }, "highlight": { "prefix": "¿", "postfix": "?", "mergeContiguous": true, "fields": [ { "field": "cm:title" }, { "field": "description", "prefix": "(", "postfix": ")" } ] } } ``` The example above changes the highlighting prefix and postfix from the default for all fields to ¿? and just for the "description" field to (). The hightlight information is added in each node entry response; here is an example partial response: ``` "entry": { "createdAt": "2016-10-12T15:24:31.202+0000", "isFolder": true, "search": { "score": 1, "highlight": [ { "field": "cm:title", "snippets": [ "Customized ¿Workflow? Process Definitions" ] }, { "field": "description", "snippets": [ "Customized (Workflow) Process Definitions" ] } ] }, ``` parameters: - in: body name: queryBody description: | Generic query API required: true schema: $ref: '#/definitions/SearchRequest' operationId: search produces: - application/json responses: '200': description: Successful response schema: $ref: '#/definitions/ResultSetPaging' default: description: Unexpected error schema: $ref: '#/definitions/Error' definitions: ## Standard definition Error: type: object required: - error properties: error: type: object required: - statusCode - briefSummary - stackTrace - descriptionURL properties: errorKey: type: string statusCode: type: integer format: int32 briefSummary: type: string stackTrace: type: string descriptionURL: type: string logId: type: string SearchRequest: type: object required: - query properties: query: $ref: '#/definitions/RequestQuery' paging: $ref: '#/definitions/RequestPagination' include: $ref: '#/definitions/RequestInclude' includeRequest: description: "When true, include the original request in the response" type: boolean default: false fields: $ref: '#/definitions/RequestFields' sort: $ref: '#/definitions/RequestSortDefinition' templates: $ref: '#/definitions/RequestTemplates' defaults: $ref: '#/definitions/RequestDefaults' localization: $ref: '#/definitions/RequestLocalization' filterQueries: $ref: '#/definitions/RequestFilterQueries' facetQueries: $ref: '#/definitions/RequestFacetQueries' facetFields: $ref: '#/definitions/RequestFacetFields' facetIntervals: $ref: '#/definitions/RequestFacetIntervals' pivots: type: array items: $ref: '#/definitions/RequestPivot' stats: type: array items: $ref: '#/definitions/RequestStats' spellcheck: $ref: '#/definitions/RequestSpellcheck' scope: $ref: '#/definitions/RequestScope' limits: $ref: '#/definitions/RequestLimits' highlight: $ref: '#/definitions/RequestHighlight' ranges: type: array items: $ref: '#/definitions/RequestRange' RequestInclude: description: | Returns additional information about the node. The following optional fields can be requested: * properties * aspectNames * path * isLink * allowableOperations * association type: array items: type: string enum: - allowableOperations - aspectNames - isLink - isLocked - path - properties RequestFields: description: A list of field names. You can use this parameter to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. The list applies to a returned individual entity or entries within a collection. If the **include** parameter is used aswell then the fields specified in the **include** parameter are returned in addition to those specified in the **fields** parameter. type: array items: type: string RequestPivot: description: A list of pivots. type: object properties: key: description: A key corresponding to a matching field facet label or stats. type: string pivots: type: array items: $ref: '#/definitions/RequestPivot' RequestLocalization: description: Localization settings type: object properties: timezone: description: A valid timezone id supported by @see java.time.ZoneId type: string locales: description: A list of Locales definied by IETF BCP 47. The ordering is significant. The first locale (leftmost) is used for sort and query localization, whereas the remaining locales are used for query only. type: array items: type: string RequestStats: description: A list of stats request. type: object properties: field: description: The stats field type: string label: description: A label to include for reference the stats field type: string min: description: The minimum value of the field type: boolean default: true max: description: The maximum value of the field type: boolean default: true sum: description: The sum of all values of the field type: boolean default: true countValues: description: The number which have a value for this field type: boolean default: true missing: description: The number which do not have a value for this field type: boolean default: true mean: description: The average type: boolean default: true stddev: description: Standard deviation type: boolean default: true sumOfSquares: description: Sum of all values squared type: boolean default: true distinctValues: description: The set of all distinct values for the field (This can be very expensive to calculate) type: boolean default: false countDistinct: description: The number of distinct values (This can be very expensive to calculate) type: boolean default: false cardinality: description: A statistical approximation of the number of distinct values type: boolean default: false cardinalityAccuracy: description: Number between 0.0 and 1.0 indicating how aggressively the algorithm should try to be accurate. Used with boolean cardinality flag. type: number format: float default: 0.3 excludeFilters: description: A list of filters to exclude type: array items: type: string percentiles: description: A list of percentile values, e.g. "1,99,99.9" type: array items: type: number format: float RequestQuery: description: Query. type: object required: - query properties: language: description: The query language in which the query is written. type: string default: afts enum: - afts - lucene - cmis userQuery: description: The exact search request typed in by the user type: string query: description: The query which may have been generated in some way from the userQuery type: string # ReponseQuery ResultSetPaging: description: Query results type: object properties: list: type: object properties: pagination: $ref: '#/definitions/Pagination' context: $ref: '#/definitions/ResultSetContext' entries: type: array items: $ref: '#/definitions/ResultSetRowEntry' ResultSetContext: description: Context that applies to the whole result set type: object properties: consistency: $ref: '#/definitions/ResponseConsistency' request: $ref: '#/definitions/SearchRequest' facetQueries: description: The counts from facet queries type: array items: type: object properties: label: type: string filterQuery: description: The filter query you can use to apply this facet type: string count: type: integer facetsFields: description: The counts from field facets type: array items: $ref: '#/definitions/ResultBuckets' facets: description: The faceted response type: array items: $ref: '#/definitions/GenericFacetResponse' spellcheck: description: | Suggested corrections If zero results were found for the original query then a single entry of type "searchInsteadFor" will be returned. If alternatives were found that return more results than the original query they are returned as "didYouMean" options. The highest quality suggestion is first. type: array items: type: object properties: "type": type: string enum: - searchInsteadFor - didYouMean suggestion: description: A suggested alternative query type: array items: type: string GenericFacetResponse: type: object properties: type: description: The facet type, eg. interval, range, pivot, stats type: string label: description: The field name or its explicit label, if provided on the request type: string buckets: description: An array of buckets and values type: array items: $ref: '#/definitions/GenericBucket' GenericBucket: description: A bucket of facet results type: object properties: label: description: The bucket label type: string filterQuery: description: The filter query you can use to apply this facet type: string display: description: An optional field for additional display information type: object metrics: description: An array of buckets and values type: array items: $ref: '#/definitions/GenericMetric' facets: description: Additional list of nested facets type: array items: type: object bucketInfo: description: Additional information of nested facet type: object properties: start: description: The start of range type: string startInclusive: description: Includes values greater or equal to "start" type: boolean end: description: The end of range type: string endInclusive: description: Includes values less than or equal to "end" type: boolean GenericMetric: description: A metric used in faceting type: object properties: type: description: The type of metric, e.g. count type: string value: description: | The metric value, e.g. {"count": 34} type: object ResultBuckets: type: object properties: label: description: The field name or its explicit label, if provided on the request type: string buckets: description: An array of buckets and values type: array items: type: object properties: label: description: The bucket label type: string filterQuery: description: The filter query you can use to apply this facet type: string count: description: The count for the bucket type: integer display: description: An optional field for additional display information type: object ResultSetRowEntry: description: A row in the result set type: object required: - entry properties: ## Standard response structure entry: $ref: '#/definitions/ResultNode' ResultNode: allOf: - $ref: '#/definitions/Node' - type: object properties: search: $ref: '#/definitions/SearchEntry' archivedByUser: $ref: '#/definitions/UserInfo' archivedAt: type: string format: date-time versionLabel: type: string versionComment: type: string SearchEntry: type: object properties: score: description: The score for this row type: number format: float highlight: description: | Highlight fragments if requested and available. A match can happen in any of the requested field. type: array items: type: object properties: field: description: The field where a match occured (one of the fields defined on the request) type: string snippets: description: Any number of snippets for the specified field highlighting the matching text type: array items: description: The highlighted fragment for the field. type: string ## Standard definition Node: type: object required: - id - name - nodeType - isFolder - isFile - createdAt - createdByUser - modifiedAt - modifiedByUser properties: id: type: string name: type: string pattern: "^(?!(.*[\\\"\\*\\\\\\>\\<\\?\\/\\:\\|]+.*)|(.*[\\.]?.*[\\.]+$)|(.*[ ]+$))" description: | The name must not contain spaces or the following special characters: * " < > \ / ? : and |. The character . must not be used at the end of the name. nodeType: type: string isFolder: type: boolean isFile: type: boolean isLocked: type: boolean default: false modifiedAt: type: string format: date-time modifiedByUser: $ref: '#/definitions/UserInfo' createdAt: type: string format: date-time createdByUser: $ref: '#/definitions/UserInfo' parentId: type: string isLink: type: boolean content: $ref: '#/definitions/ContentInfo' aspectNames: type: array items: type: string properties: type: object allowableOperations: type: array items: type: string path: $ref: '#/definitions/PathInfo' ## Standard definition UserInfo: type: object required: - displayName - id properties: displayName: type: string id: type: string ## Standard definition ContentInfo: type: object required: - mimeType - mimeTypeName - sizeInBytes properties: mimeType: type: string mimeTypeName: type: string sizeInBytes: type: integer encoding: type: string mimeTypeGroup: type: string ## Standard definition PathElement: type: object properties: id: type: string name: type: string ## Standard definition PathInfo: type: object properties: elements: type: array items: $ref: '#/definitions/PathElement' name: type: string isComplete: type: boolean RequestDefaults: description: Common query defaults type: object properties: textAttributes: description: | A list of query fields/properties used to expand TEXT: queries. The default is cm:content. You could include all content properties using d:content or list all individual content properties or types. As more terms are included the query size, complexity, memory impact and query time will increase. type: array items: type: string default: cm:content defaultFTSOperator: description: | The default way to combine query parts when AND or OR is not explicitly stated - includes ! - + one two three (one two three) type: string default: AND enum: - AND - OR defaultFTSFieldOperator: description: | The default way to combine query parts in field query groups when AND or OR is not explicitly stated - includes ! - + FIELD:(one two three) type: string default: AND enum: - AND - OR namespace: description: The default name space to use if one is not provided type: string default: cm defaultFieldName: type: string default: TEXT RequestTemplates: description: | Templates usewd for query expansion. A template called "WOOF" defined as "%(cm:name cm:title)" allows WOOF:example to generate cm:name:example cm:name:example type: array items: type: object properties: name: description: The template name type: string template: description: The template type: string RequestScope: description: Scope type: object properties: locations: description: | The locations to include in the query type: string enum: - nodes - versions - deleted-nodes RequestPagination: type: object properties: maxItems: description: The maximum number of items to return in the query results type: integer minimum: 1 default: 100 skipCount: description: The number of items to skip from the start of the query set type: integer minimum: 0 default: 0 Pagination: type: object required: - count - hasMoreItems - skipCount - maxItems properties: count: type: integer format: int64 description: | The number of objects in the entries array. hasMoreItems: type: boolean description: | A boolean value which is **true** if there are more entities in the collection beyond those in this response. A true value means a request with a larger value for the **skipCount** or the **maxItems** parameter will return more entities. totalItems: type: integer format: int64 description: | An integer describing the total number of entities in the collection. The API might not be able to determine this value, in which case this property will not be present. skipCount: type: integer format: int64 description: | An integer describing how many entities exist in the collection before those included in this list. maxItems: type: integer format: int64 description: | The value of the **maxItems** parameter used to generate this list, or if there was no **maxItems** parameter the default value is 100 ResponseConsistency: description: The consistency state of the index used to execute the query type: object properties: lastTxId: description: The id of the last indexed transaction type: integer RequestFacetQueries: description: Facet queries to include type: array items: type: object properties: query: description: A facet query type: string label: description: A label to include in place of the facet query type: string RequestFacetFields: description: | Simple facet fields to include The Properties reflect the global properties related to field facts in SOLR. They are descripbed in detail by the SOLR documentation type: object properties: facets: description: | Define specifc fields on which to facet (adds SOLR facet.field and f..facet.* options) type: array items: $ref: '#/definitions/RequestFacetField' RequestFacetField: description: A simple facet field type: object properties: field: description: The facet field type: string label: description: A label to include in place of the facet field type: string prefix: description: Restricts the possible constraints to only indexed values with a specified prefix. type: string sort: type: string enum: - COUNT - INDEX method: type: string enum: - ENUM - FC missing: description: When true, count results that match the query but which have no facet value for the field (in addition to the Term-based constraints). type: boolean default: false limit: type: integer offset: type: integer mincount: type: integer description: The minimum count required for a facet field to be included in the response. default: 1 facetEnumCacheMinDf: type: integer excludeFilters: description: | Filter Queries with tags listed here will not be included in facet counts. This is used for multi-select facetting. type: array items: type: string RequestLimits: description: Limit the time and resources used for query execution type: object properties: permissionEvaluationTime: description: Maximum time for post query permission evaluation type: integer default: 20000 permissionEvaluationCount: description: Maximum count of post query permission evaluations type: integer default: 2000 RequestFacetIntervals: description: Facet Intervals type: object properties: sets: description: Sets the intervals for all fields. type: array items: $ref: '#/definitions/RequestFacetSet' intervals: description: Specifies the fields to facet by interval. type : array items: type: object properties: field: description: The field to facet on type: string label: description: A label to use to identify the field facet type: string sets: description: Sets the intervals for all fields. type: array items: $ref: '#/definitions/RequestFacetSet' RequestFacetSet: description: The interval to Set type: object properties: label: description: A label to use to identify the set type: string start: description: The start of the range type: string end: description: The end of the range type: string startInclusive: description: When true, the set will include values greater or equal to "start" type: boolean default: true endInclusive: description: When true, the set will include values less than or equal to "end" type: boolean default: true RequestFilterQueries: description: Filter Queries. Constraints that apply to the results set but do not affect the score of each entry. type: array items: type: object properties: query: description: | The filter query expression. For multi-select facets selected facets must be order together type: string tags: description: Tags used exclude the filters from facet evaluation for multi-select facet support type: array items: type: string RequestSortDefinition: description: How to sort the rows? An array of sort specifications. The array order defines the ordering precedence. type: array items: type: object properties: type: description: How to order - using a field, when position of the document in the index, score/relevence. type: string default: FIELD enum: - FIELD - DOCUMENT - SCORE field: description: The name of the field type: string ascending: description: The sort order. (The ordering of nulls is determined by the SOLR configuration) type: boolean default: false RequestSpellcheck: description: | Request that spellcheck fragments to be added to result set rows The properties reflect SOLR spellcheck parameters. type: object properties: query: type: string RequestHighlight: description: | Request that highlight fragments to be added to result set rows The properties reflect SOLR highlighting parameters. type: object properties: prefix: description: The string used to mark the start of a highlight in a fragment. type: string postfix: description: The string used to mark the end of a highlight in a fragment. type: string snippetCount: description: The maximum number of distinct highlight snippets to return for each highlight field. type: integer fragmentSize: description: The character length of each snippet. type: integer maxAnalyzedChars: description: The number of characters to be considered for highlighting. Matches after this count will not be shown. type: integer mergeContiguous: description: If fragments over lap they can be merged into one larger fragment type: boolean usePhraseHighlighter: description: Should phrases be identified. type: boolean fields: description: The fields to highlight and field specific configuration properties for each field type: array items: type: object properties: field: description: The name of the field to highlight. type: string snippetCount: type: integer fragmentSize: type: integer mergeContiguous: type: boolean prefix: type: string postfix: type: string RequestRange: description: Facet range type: object properties: field: description: The name of the field to perform range type: string start: description: The start of the range type: string end: description: The end of the range type: string gap: description: Bucket size type: string hardend: description: If true means that the last bucket will end at “end” even if it is less than “gap” wide. type: boolean other: description: before, after, between, non, all type: array items: type: string include: description: lower, upper, edge, outer, all type: array items: type: string label: description: A label to include as a pivot reference type: string excludeFilters: description: Filter queries to exclude when calculating statistics type: array items: type: string