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"}] ``` For **spell checking** you can use a query like this: ```JSON { "query": { "query": "cm:title:alfrezco", "language": "afts" }, "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", "language": "afts" }, "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 } ]} ] }, ``` 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: required: - query properties: query: $ref: '#/definitions/RequestQuery' paging: $ref: '#/definitions/RequestPagination' include: $ref: '#/definitions/RequestInclude' fields: $ref: '#/definitions/RequestFields' sort: $ref: '#/definitions/RequestSortDefinition' templates: $ref: '#/definitions/RequestTemplates' defaults: $ref: '#/definitions/RequestDefaults' filterQueries: $ref: '#/definitions/RequestFilterQueries' facetQueries: $ref: '#/definitions/RequestFacetQueries' facetFields: $ref: '#/definitions/RequestFacetFields' spellcheck: $ref: '#/definitions/RequestSpellcheck' scope: $ref: '#/definitions/RequestScope' limits: $ref: '#/definitions/RequestLimits' highlight: $ref: '#/definitions/RequestHighlight' 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 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 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' facetQueries: description: The counts from facet queries type: array items: type: object properties: label: type: string count: type: number facetFields: description: The counts from field facets type: array items: 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 count: description: The count for the bucket type: number display: description: An optional field for additional display information type: object 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 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: type: object properties: field: description: 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 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: number fragmentSize: description: The character length of each snippet. type: number maxAnalyzedChars: description: The number of characters to be considered for highlighting. Matches after this count will not be shown. type: number 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: number fragmentSize: type: number mergeContiguous: type: boolean prefix: type: string postfix: type: string