# Search Application Client
The Search Application Client is a JavaScript library that provides functionality for interacting with a search application in Elasticsearch.
> ℹ️ The Search Application Client is in **technical preview** and is subject to change.
## Quick Access
Here are some quick links to the important sections:
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Advanced Usage](#advanced-usage)
- [Examples](#examples)
## Installation
To install the Search Application Client, you can use npm or yarn.
### Using npm:
```bash
npm install @elastic/search-application-client
```
### Using yarn:
```bash
yarn add @elastic/search-application-client
```
### In Browser via CDN
```html
```
## Usage
### Importing the Client
You can import the Search Application Client in your JavaScript or TypeScript file using the following import statement:
```javascript
import SearchApplicationClient from '@elastic/search-application-client';
```
### Creating an Instance of Client
To use the Search Application Client, create an instance by calling the function returned by the imported module:
```javascript
const client = SearchApplicationClient(applicationName, endpoint, apiKey, params);
```
- applicationName: The name of the search application.
- endpoint: The URL of the search application's endpoint.
- apiKey: The API key for accessing the search application.
- params (optional): Additional parameters to be passed to the client.
- apiOptions (optional): Additional options to be passed to the API client.
- cacheExpiration (optional): The cache expiration time in milliseconds. Default: 3600000 (one hour).
- cache (optional): Enable/disables the cache. Default: true.
- headers (optional): Additional headers to be passed to the API client.
- Returns: A function that returns a new QueryBuilder instance.
### Using the Client
The Search Application Client provides a QueryBuilder class that allows you to build complex search queries:
```javascript
const results = await client()
.query('John')
.search()
```
The search method returns a Promise that resolves with the search results.
#### Use facets
To use facets filtering, specify facets in the client initialization:
```javascript
const client = SearchApplicationClient('*search-application-name*', '*elasticsearch-endpoint*', '*apiKey*', {
facets: {
category: { type: 'terms', field: 'category.keyword', size: 10 },
price: { type: 'stats', field: 'price', size: 10, disjunctive: true },
},
});
const results = await client()
.addFacetFilter('category', 'electronics')
.addFacetFilter('price', { from: 100, to: 1000 })
.addFacetFilter('author', 'orwell') // ❌ Throw an error, because the facet is not specified during initialization
.setSort({'price': 'desc'})
.search()
```
#### Use sorting
To use sorting, specify the field name and the sort order or pass _score to sort by relevance:
```javascript
const results = await client()
.setSort([{'publish_date': 'desc'}, "_score"])
.search()
```
#### Use pagination
To use pagination, set the page number and the page size:
```javascript
const results = await client()
.setPageSize(20)
.setFrom(20 * 2) // For the third page
.search()
```
By default, page size is 10
#### Use additional parameters
```javascript
const results = await client()
.addParameter('custom-parameter', 'custom-value')
.search()
```
## API Reference
### ```SearchApplicationClient()```
Function to initialize searchApplicationClient and returns function to create an instance of the QueryBuilder.
- ```applicationName (string)```: The name of the search application.
- ```endpoint (string)```: The URL of the search application's endpoint.
- ```apiKey (string)```: The API key for accessing the search application.
- ```params? (Params)```: Additional parameters to be passed to the client.
Returns: function that returns new QueryBuilder instance.
### ```QueryBuilder```
This class provides methods for building search queries.
- ```query(query: string): QueryBuilder```
Sets the search query. Returns: QueryBuilder instance.
- ```addFacetFilter(field: string, value: FilterFieldValue): QueryBuilder```
Adds a facet filter to narrow down the search results. Returns: QueryBuilder instance.
- ```field (string)```: The field name of the facet filter.
- ```value (string | string[] | number | number[])```: The value or range of values for the facet filter.
- ```addParameter(field: string, value: unkown): QueryBuilder```
Adds a parameter to the query. Returns: QueryBuilder instance.
- ```setPageSize(size: number): QueryBuilder```
Sets the size for maximum number of results to return. Returns: QueryBuilder instance.
- ```setFrom(value: number): QueryBuilder```
Defines the number of results to skip, defaulting to 0. Returns: QueryBuilder instance.
- ```setSort(sort: SortFields): QueryBuilder```
Sets the sorting criteria for the search results. Returns: QueryBuilder instance.
- ```sort (Record | '_score')[])```: The sorting criteria for the search results.
- ```search(): Promise```
Sends the search request to the search application. Use generic types for specify ```hits._source``` type.
Returns: A promise that resolves to the search results.
- hits: An array of search hits.
- facets: An array of facet results.
- aggregations: An object containing aggregation results.
- total: The total number of search results.
- took: The time taken for the search request.
Please refer to the code and type definitions for more details on the available methods and their parameters.
## Advanced Usage
### Boilerplate template
```
PUT _application/search_application/example-app
{
"indices": ["example-index"],
"template": {
"script": {
"lang": "mustache",
"source": """
{
"query": {
"bool": {
"must": [
{{#query}}
{
"query_string": {
"query": "{{query}}"
}
}
{{/query}}
],
"filter": {{#toJson}}_es_filters{{/toJson}}
}
},
"aggs": {{#toJson}}_es_aggs{{/toJson}},
"from": {{from}},
"size": {{size}},
"sort": {{#toJson}}_es_sort_fields{{/toJson}}
}
""",
"params": {
"query": "",
"_es_filters": {},
"_es_aggs": {},
"_es_sort_fields": {},
"size": 10,
"from": 0
}
}
}
}
```
### Using custom template
To use custom template you can update boilerplate template within specific properties or params like highlight property:
```
PUT _application/search_application/example-app
{
"indices": ["example-index"],
"template": {
"script": {
"lang": "mustache",
"source": """
{
"query": {
"bool": {
"must": [
{{#query}}
// ...
{{/query}}
],
"filter": {{#toJson}}_es_filters{{/toJson}}
}
},
"_source": {
"includes": ["title", "plot"]
},
"highlight": {
"fields": {
"title": { "fragment_size": 0 },
"plot": { "fragment_size": 200 }
}
},
"aggs": {{#toJson}}_es_aggs{{/toJson}},
"from": {{from}},
"size": {{size}},
"sort": {{#toJson}}_es_sort_fields{{/toJson}}
}
""",
"params": {
"query": "",
"_es_filters": {},
"_es_aggs": {},
"_es_sort_fields": {},
"size": 10,
"from": 0
}
}
}
}
```
### Using dictionary for template
To use template with typechecking you can update your template with prebuilded json schema by running command:
```bash
npx @elastic/search-application-client update-template
```
Once you have updated the template it will use the schema for typechecking of params for each request.
## Examples
You can find usage examples in the [examples/sandbox](./examples/sandbox/README.md) directory of this repository. These examples demonstrate how to use the search-application-client library.