alfresco-js-api/definitions/alfresco-search.yaml

JavaScript client library for the Alfresco REST API

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 <em> 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.<field>.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