Skip to main content

Perform a Search Query Aggregation

POST 
/search/aggregate

Performs a search query aggregation and returns the aggregation result. By default, you can page a maximum of 10,000 search result records. To page past 10,000 records, you can use searchAfter paging. Refer to Paginating Search Queries for more information about how to implement searchAfter paging.

Request​

Query Parameters

    offset int32

    Default value: 0

    Offset into the full result set. Usually specified with limit to paginate through the results. See V3 API Standard Collection Parameters for more information.

    Example: 0
    limit int32

    Possible values: <= 250

    Default value: 250

    Max number of results to return. See V3 API Standard Collection Parameters for more information.

    Example: 250
    count boolean

    If true it will populate the X-Total-Count response header with the number of results that would be returned if limit and offset were ignored.

    Since requesting a total count can have a performance impact, it is recommended not to send count=true if that value will not be used.

    See V3 API Standard Collection Parameters for more information.

    Example: true

Body

required

    indices Index (string)[]

    Possible values: [accessprofiles, accountactivities, entitlements, events, identities, roles, *]

    The names of the Elasticsearch indices in which to search. If none are provided, then all indices will be searched.

    queryType QueryType (string)

    Possible values: [DSL, SAILPOINT, TEXT, TYPEAHEAD]

    Default value: SAILPOINT

    The type of query to use. By default, the SAILPOINT query type is used, which requires the query object to be defined in the request body. To use the queryDsl or typeAheadQuery objects in the request, you must set the type to DSL or TYPEAHEAD accordingly. Additional values may be added in the future without notice.

    queryVersion ElasticVersion (string)

    Default value: 5.2

    The current Elasticserver version.

    query

    object

    Query parameters used to construct an Elasticsearch query object.

    query string

    The query using the Elasticsearch Query String Query syntax from the Query DSL extended by SailPoint to support Nested queries.

    fields string

    The fields the query will be applied to. Fields provide you with a simple way to add additional fields to search, without making the query too complicated. For example, you can use the fields to specify that you want your query of "a*" to be applied to "name", "firstName", and the "source.name". The response will include all results matching the "a*" query found in those three fields. A field's availability depends on the indices being searched. For example, if you are searching "identities", you can apply your search to the "firstName" field, but you couldn't use "firstName" with a search on "access profiles". Refer to the response schema for the respective lists of available fields.

    timeZone string

    The time zone to be applied to any range query related to dates.

    innerHit

    object

    The innerHit query object returns a flattened list of results for the specified nested type.

    query stringrequired

    The search query using the Elasticsearch Query String Query syntax from the Query DSL extended by SailPoint to support Nested queries.

    type stringrequired

    The nested type to use in the inner hits query. The nested type Nested Type refers to a document "nested" within another document. For example, an identity can have nested documents for access, accounts, and apps.

    queryDsl object

    The search query using the Elasticsearch Query DSL syntax.

    textQuery

    object

    Query parameters used to construct an Elasticsearch text query object.

    terms string[]required

    Words or characters that specify a particular thing to be searched for.

    fields string[]required

    The fields to be searched.

    matchAny boolean

    Indicates that at least one of the terms must be found in the specified fields; otherwise, all terms must be found.

    contains boolean

    Indicates that the terms can be located anywhere in the specified fields; otherwise, the fields must begin with the terms.

    typeAheadQuery

    object

    Query parameters used to construct an Elasticsearch type ahead query object. The typeAheadQuery performs a search for top values beginning with the typed values. For example, typing "Jo" results in top hits matching "Jo." Typing "Job" results in top hits matching "Job."

    query stringrequired

    The type ahead query string used to construct a phrase prefix match query.

    field stringrequired

    The field on which to perform the type ahead search.

    nestedType string

    The nested type.

    maxExpansions int32

    Possible values: >= 1 and <= 1000

    Default value: 10

    The number of suffixes the last term will be expanded into. Influences the performance of the query and the number results returned. Valid values: 1 to 1000.

    size int32

    Possible values: >= 1

    Default value: 100

    The max amount of records the search will return.

    sort string

    Default value: desc

    The sort order of the returned records.

    sortByValue boolean

    The flag that defines the sort type, by count or value.

    includeNested boolean

    Default value: true

    Indicates whether nested objects from returned search results should be included.

    queryResultFilter

    object

    Allows the query results to be filtered by specifying a list of fields to include and/or exclude from the result documents.

    includes string[]

    The list of field names to include in the result documents.

    excludes string[]

    The list of field names to exclude from the result documents.

    aggregationType AggregationType (string)

    Possible values: [DSL, SAILPOINT]

    Default value: DSL

    Enum representing the currently available query languages for aggregations, which are used to perform calculations or groupings on search results.

    Additional values may be added in the future without notice.

    aggregationsVersion ElasticVersion (string)

    Default value: 5.2

    The current Elasticserver version.

    aggregationsDsl object

    The aggregation search query using Elasticsearch Aggregations syntax.

    aggregations

    object

    nested

    object

    The nested aggregation object.

    name stringrequired

    The name of the nested aggregate to be included in the result.

    type stringrequired

    The type of the nested object.

    metric

    object

    The calculation done on the results of the query

    name stringrequired

    The name of the metric aggregate to be included in the result. If the metric aggregation is omitted, the resulting aggregation will be a count of the documents in the search results.

    type MetricType (string)

    Possible values: [COUNT, UNIQUE_COUNT, AVG, SUM, MEDIAN, MIN, MAX]

    Default value: UNIQUE_COUNT

    Enum representing the currently supported metric aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The field the calculation is performed on.

    Prefix the field name with '@' to reference a nested object.

    filter

    object

    An additional filter to constrain the results of the search query.

    name stringrequired

    The name of the filter aggregate to be included in the result.

    type SearchFilterType (string)

    Possible values: [TERM]

    Default value: TERM

    Enum representing the currently supported filter aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The search field to apply the filter to.

    Prefix the field name with '@' to reference a nested object.

    value stringrequired

    The value to filter on.

    bucket

    object

    The bucket to group the results of the aggregation query by.

    name stringrequired

    The name of the bucket aggregate to be included in the result.

    type BucketType (string)

    Possible values: [TERMS]

    Default value: TERMS

    Enum representing the currently supported bucket aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The field to bucket on. Prefix the field name with '@' to reference a nested object.

    size int32

    Maximum number of buckets to include.

    minDocCount int32

    Minimum number of documents a bucket should have.

    subAggregation

    object

    Aggregation to be performed on the result of the parent bucket aggregation.

    nested

    object

    The nested aggregation object.

    name stringrequired

    The name of the nested aggregate to be included in the result.

    type stringrequired

    The type of the nested object.

    metric

    object

    The calculation done on the results of the query

    name stringrequired

    The name of the metric aggregate to be included in the result. If the metric aggregation is omitted, the resulting aggregation will be a count of the documents in the search results.

    type MetricType (string)

    Possible values: [COUNT, UNIQUE_COUNT, AVG, SUM, MEDIAN, MIN, MAX]

    Default value: UNIQUE_COUNT

    Enum representing the currently supported metric aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The field the calculation is performed on.

    Prefix the field name with '@' to reference a nested object.

    filter

    object

    An additional filter to constrain the results of the search query.

    name stringrequired

    The name of the filter aggregate to be included in the result.

    type SearchFilterType (string)

    Possible values: [TERM]

    Default value: TERM

    Enum representing the currently supported filter aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The search field to apply the filter to.

    Prefix the field name with '@' to reference a nested object.

    value stringrequired

    The value to filter on.

    bucket

    object

    The bucket to group the results of the aggregation query by.

    name stringrequired

    The name of the bucket aggregate to be included in the result.

    type BucketType (string)

    Possible values: [TERMS]

    Default value: TERMS

    Enum representing the currently supported bucket aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The field to bucket on. Prefix the field name with '@' to reference a nested object.

    size int32

    Maximum number of buckets to include.

    minDocCount int32

    Minimum number of documents a bucket should have.

    subAggregation

    object

    Aggregation to be performed on the result of the parent bucket aggregation.

    nested

    object

    The nested aggregation object.

    name stringrequired

    The name of the nested aggregate to be included in the result.

    type stringrequired

    The type of the nested object.

    metric

    object

    The calculation done on the results of the query

    name stringrequired

    The name of the metric aggregate to be included in the result. If the metric aggregation is omitted, the resulting aggregation will be a count of the documents in the search results.

    type MetricType (string)

    Possible values: [COUNT, UNIQUE_COUNT, AVG, SUM, MEDIAN, MIN, MAX]

    Default value: UNIQUE_COUNT

    Enum representing the currently supported metric aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The field the calculation is performed on.

    Prefix the field name with '@' to reference a nested object.

    filter

    object

    An additional filter to constrain the results of the search query.

    name stringrequired

    The name of the filter aggregate to be included in the result.

    type SearchFilterType (string)

    Possible values: [TERM]

    Default value: TERM

    Enum representing the currently supported filter aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The search field to apply the filter to.

    Prefix the field name with '@' to reference a nested object.

    value stringrequired

    The value to filter on.

    bucket

    object

    The bucket to group the results of the aggregation query by.

    name stringrequired

    The name of the bucket aggregate to be included in the result.

    type BucketType (string)

    Possible values: [TERMS]

    Default value: TERMS

    Enum representing the currently supported bucket aggregation types. Additional values may be added in the future without notice.

    field stringrequired

    The field to bucket on. Prefix the field name with '@' to reference a nested object.

    size int32

    Maximum number of buckets to include.

    minDocCount int32

    Minimum number of documents a bucket should have.

    sort string[]

    The fields to be used to sort the search results. Use + or - to specify the sort direction.

    searchAfter string[]

    Used to begin the search window at the values specified. This parameter consists of the last values of the sorted fields in the current record set. This is used to expand the Elasticsearch limit of 10K records by shifting the 10K window to begin at this value. It is recommended that you always include the ID of the object in addition to any other fields on this parameter in order to ensure you don't get duplicate results while paging. For example, when searching for identities, if you are sorting by displayName you will also want to include ID, for example ["displayName", "id"]. If the last identity ID in the search result is 2c91808375d8e80a0175e1f88a575221 and the last displayName is "John Doe", then using that displayName and ID will start a new search after this identity. The searchAfter value will look like ["John Doe","2c91808375d8e80a0175e1f88a575221"]

    filters

    object

    The filters to be applied for each filtered field name.

    property name*

    Filter

    type FilterType (string)

    Possible values: [EXISTS, RANGE, TERMS]

    Enum representing the currently supported filter types. Additional values may be added in the future without notice.

    range

    object

    The range of values to be filtered.

    lower

    object

    The lower bound of the range.

    value stringrequired

    The value of the range's endpoint.

    inclusive boolean

    Indicates if the endpoint is included in the range.

    upper

    object

    The upper bound of the range.

    value stringrequired

    The value of the range's endpoint.

    inclusive boolean

    Indicates if the endpoint is included in the range.

    terms string[]

    The terms to be filtered.

    exclude boolean

    Indicates if the filter excludes results.

Responses​

Aggregation results.

Response Headers

  • X-Total-Count

    integer

    Example: 5

    The total result count (returned only if the count parameter is specified as true).

Schema

    aggregations object

    The document containing the results of the aggregation. This document is controlled by Elasticsearch and depends on the type of aggregation query that is run.

    See Elasticsearch Aggregations documentation for information.

    hits

    object[]

    The results of the aggregation search query.

  • Array [

    • oneOf

    More complete representation of an access profile.

    id stringrequired

    The unique ID of the referenced object.

    name stringrequired

    The human readable name of the referenced object.

    description string

    Access item's description.

    created date-timenullable

    ISO-8601 date-time referring to the time when the object was created.

    modified date-timenullable

    ISO-8601 date-time referring to the time when the object was last modified.

    synced date-timenullable

    ISO-8601 date-time referring to the date-time when object was queued to be synced into search database for use in the search API.
    This date-time changes anytime there is an update to the object, which triggers a synchronization event being sent to the search database. There may be some delay between the synced time and the time when the updated data is actually available in the search API.

    enabled boolean

    Indicates whether the access item is currently enabled.

    requestable boolean

    Default value: true

    Indicates whether the access item can be requested.

    requestCommentsRequired boolean

    Indicates whether comments are required for requests to access the item.

    owner

    object

    Owner's identity.

    type string

    Possible values: [IDENTITY]

    Owner's DTO type.

    id string

    Owner's identity ID.

    name string

    Owner's display name.

    email string

    Owner's email.

    _type stringrequired

    Possible values: [accessprofile, accountactivity, account, aggregation, entitlement, event, identity, role]

    Access profile's document type. This enum represents the currently supported document types. Additional values may be added in the future without notice.

    source

    object

    Access profile's source.

    id string

    Source's ID.

    name string

    Source's name.

    entitlements

    object[]

    Entitlements the access profile has access to.

  • Array [

    • hasPermissions boolean

    Indicates whether the entitlement has permissions.

    description string

    Entitlement's description.

    attribute string

    Entitlement attribute's name.

    value string

    Entitlement's value.

    schema string

    Entitlement's schema.

    privileged boolean

    Indicates whether the entitlement is privileged.

    id string

    Entitlement's ID.

    name string

    Entitlement's name.

  • ]

    • entitlementCount integer

    Number of entitlements.

    tags string[]

    Tags that have been applied to the object.

  • ]

Loading...