search.query()

Retrieve search results that match the provided query.

Definition

client.search.query({
continuation = null,
excludeIds = [],
excludeSelf = false,
followContinuations = false,
includeDisabled = false,
organizationId = null,
organizationIds = [],
query = {},
resultsFormat = 'entities',
returnFields = [...defaultFields],
sort = [],
types = []
}):Promise<SearchResults,Error>

Parameters

At least one of organizationId or organizationIds (with length >= 1) must be provided.

NameTypeDescription
continuation?stringA reference to a previous search. When provided, it causes the next page of results to be returned. When not provided, indicates a new search.
excludeIds?Array<string>A list of IDs to exclude from search results
excludeSelf?booleanWhether to exclude the current user from search results (default: false)
followContinuations?booleanWhether to automatically follow every continuation to retrieve all pages of results (default: false). This can feel slower to users, and it's generally preferable to process and display the results of each page as it comes in.
includeDisabled?booleanWhether to include disabled user accounts in the search results (default: false)
organizationId?string|?OrganizationOrganization to search
organizationIds?Array<string|Organization>Organizations to search
querySearchQueryA SearchQuery object (described below) which indicates the search criteria
resultsFormat?stringWhether to return entire entities (value: entities, the default) or just IDs (value: ids)
returnFields?Array<string>Which fields should be returned for each search result, when resultsFormat is entities. See the Default Values for returnFields section below for defauls
sort?Array<string>Which fields should be used to sort and paginate the results in ascending order; if not provided, the sort order will be best match first.
typesArray<string>Which types of entities may be returned. See SearchTypes for possible values. Callers must provide at least one type.

SearchQuery

The TigerConnect platform supports several of the ElasticSearch query options.

In the example below:

{
bool: {
must: {
'field1': 'value1',
'field2': 'value2'
},
must_not: {
'field3': 'value3',
'field4': 'value4'
}
}
}

Results will be filtered like this:

  • If field1 matches value1
  • AND field2 matches value2
  • AND field3 does not match value3
  • AND field4 does not match value4.

Special cases:

  • 'any': 'someValue': Succeeds if any returnFields values match someValue
  • If a field does not belong to an entity, it will be matched against metadata

Default Values for returnFields

If the returnFields property is not specified, the following string fields (subject to later change at our discretion) will be returned for any type of entity:

  • avatar
  • conversation_id
  • department
  • description
  • display_name
  • dnd_auto_forward_receiver
  • dnd
  • first_name
  • is_public
  • last_login_time
  • last_name
  • name
  • num_members
  • organization_key
  • pagers
  • status
  • title
  • token

SearchTypes

The types field should be an Array of one or more of the following JS enum values:

  • client.enums.SearchType.DISTRIBUTION_LIST
  • client.enums.SearchType.FORUM
  • client.enums.SearchType.GROUP
  • client.enums.SearchType.ORGANIZATION
  • client.enums.SearchType.PATIENT - If attempting to search for a patient, types array should only contain 'patient' type
  • client.enums.SearchType.TAG - this indicates a role tag
  • client.enums.SearchType.USER

Returns

An error will be thrown if any of the arguments are invalid.

Otherwise, once the returned Promise is resolved, you will have access to a SearchResults object with the following structure.

SearchResults

NameTypeDescription
metadataSearchResultsMetadataSummary data about the number of results returned and pagination. See SearchResultsMetadata below for details.
resultsArray<SearchResult>The results from the search query. See SearchResult below for details.

SearchResultsMetadata

NameTypeDescription
continuation?stringIf more results are available, this will be a continuation string that can be passed into the same query to get the next page of results
firstHitnumberThe position of the first returned entity within the entire unpaginated result set in ElasticSearch
totalHitsnumberThe total number of unpaginated results which matched the query, not all of which might be returned yet

SearchResult

NameTypeDescription
conversationIdstring|nullThe ID of the conversation (if applicable) which is associated with this entity in the context of this organization. Some entities (like roles) cannot have direct conversations, so null will be returned for them.
entityIdstringThe ID of the entity, which is generally also available as entity.id
entityTypestringThe type of the entity
entityObjectThe entity that was returned from the search query
idstringUnique identifier for the search result
metadataObjectMetadata associated with the entity, which is generally also available in entity.metadata
organizationIdstringThe organization of the entity

Examples

const { metadata, results } = await client.search.query({
types: ['user', 'group'],
query: { displayName: 'al' },
organizationId: 'some-org-id'
});
console.log('found', results.length, 'results')
results.forEach(function (result, i) {
console.log(i, result.entityType, result.entity.displayName);
});