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
matchesvalue1
- AND
field2
matchesvalue2
- AND
field3
does not matchvalue3
- AND
field4
does not matchvalue4
.
Special cases:
'any': 'someValue'
: Succeeds if anyreturnFields
values matchsomeValue
- 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' typeclient.enums.SearchType.TAG
- this indicates a role tagclient.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);});