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.

Name	Type	Description
`continuation`	`?string`	A 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`	`?boolean`	Whether to exclude the current user from search results (default: `false`)
`followContinuations`	`?boolean`	Whether 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`	`?boolean`	Whether to include disabled user accounts in the search results (default: `false`)
`organizationId`	`?string`\|`?`Organization	Organization to search
`organizationIds`	`?Array<string`\|Organization`>`	Organizations to search
`query`	`SearchQuery`	A SearchQuery object (described below) which indicates the search criteria
`resultsFormat`	`?string`	Whether 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.
`types`	`Array<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

Name	Type	Description
`metadata`	`SearchResultsMetadata`	Summary data about the number of results returned and pagination. See SearchResultsMetadata below for details.
`results`	`Array<SearchResult>`	The results from the search query. See SearchResult below for details.

SearchResultsMetadata

Name	Type	Description
`continuation`	`?string`	If 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
`firstHit`	`number`	The position of the first returned entity within the entire unpaginated result set in ElasticSearch
`totalHits`	`number`	The total number of unpaginated results which matched the query, not all of which might be returned yet

SearchResult

Name	Type	Description
`conversationId`	`string`\|`null`	The 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.
`entityId`	`string`	The ID of the entity, which is generally also available as `entity.id`
`entityType`	`string`	The type of the entity
`entity`	`Object`	The entity that was returned from the search query
`id`	`string`	Unique identifier for the search result
`metadata`	`Object`	Metadata associated with the entity, which is generally also available in `entity.metadata`
`organizationId`	`string`	The 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);
});