@lableb/javascript-sdk/documentation/search.md

Lableb cloud search client for javascript

# Lableb's Client | Search API

After creating a new instance of Lableb's Client,

```js
const lablebClient = LablebClient({
    APIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
});
```

You can use the search function as 

```js
const { code, response, time } = await lablebClient.search(options);

const searchResults = response.results;
```

----------------------

## Options

All options has types validation built in for you, in case you mis-typed something, And if you're using [typescript](https://github.com/microsoft/TypeScript) the code editor will tell you for any mis-typed argument instantly.

Options are of three categories:
- search specific
- globally shared, which can be used to override any global option for this search function call
- user related

----------------------

### Search specific options

| field   | type   | description |
| ------- | ------ | ----------- |                                                                 
| query*  | string | usually your end users query |                
| facets  | object | add filters to your search request with an easy to use object syntax(example below) |
| sort    | string | sort your results by specific field and specific order |
| limit   | number | limit your search results to some number |
| skip    | number | used for paginated data |


  - Facets syntax
  
    Facets enable easy filtering throughout your data, say for example that your data has tags in them(where each document(data) can have one to many tags in it). 

    To quickly filter the documents for the tags `brilliant` and `great` you can send a facet object that   contains both values
    
    ```js
    await lablebClient.search({
        facets: {
            tags: ['brilliant', 'great']
        }
    });
    ```


  - Sort syntax

    You type the field name followed by the `asc` or `desc` to sort data by that field in an ascending or   descending order respectively.
    
    Example:
    
    ```js
    await lablebClient.search({
        sort: "date desc"
    });
    ```


----------------------



### Globally shared options

Passing these options to the search function will override any globally passed options to the main `LablebClient` of the same name.

| field         | type   | description |
| ------------- | ------ | ----------- |
| platformName  | string | your platform name in small-letters |
| indexName     | string | the used index name for the search function |
| searchHandler | string | the used search handler for the search function |
| APIKey        | string | your search API Key copied from [Lableb Dashboard](https://dashboard.lableb.com) |



----------------------


### User related options

Useful to track your users behavior later on, because knowing your users can help you better develop your platform/product.

| field         | type   | description |
| ------------- | ------ | ----------- |
| userId        | string | end user id |
| userIp        | string | end user IP address |
| userCountry   | string | end user country code(ISO-3166) |
| sessionId     | string | uniques session Id for your end user |
| sessionIdGenerator  | function | pass callback that generate unique session id string |

----------------------


#### Alternative syntax for async code

```js
let lablebClient = LablebClient({
    APIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
})

  lablebClient.search(options)
  .then(searchResponse => {

      const { code, response, time } = searchResponse;

      const searchResults = response.results;
  })
  .catch(console.error);;

```


----------------------


### Search Response


```js
const searchResponse = await lablebClient.search(options);
```


| field                        | type   | description |
| ---------------------------- | ------ | ----------- |
| time                         | number | time spent for the request in milliseconds |
| code                         | number | http response code                         |
| [response](#search-results)  | object | [search results](#search-results)          |




### Search Results

| field                         | type   | description |
| ----------------------------- | ------ | ----------- |
| found_documents               | number | documents count found for the given search request |
| [results](#results-example)   | array  | array of documents each has at least an `id` and a `feedback` object |
| [facets](#facets-example)     | object | contains filters keywords that can be used to further filters the returned documents |



---------------------



#### Search Response Examples



##### Results Example

```json
[
  { id: "8112-cmb", feedback: { query: "water", userCountry: "AE", ... }, ...fields },
  { id: "9142-pam", feedback: { query: "water", userCountry: "AE", ... }, ...fields },
  { id: "2712-alq", feedback: { query: "water", userCountry: "AE", ... }, ...fields },
  { id: "2522-sgm", feedback: { query: "water", userCountry: "AE", ... }, ...fields },
  { id: "8156-baj", feedback: { query: "water", userCountry: "AE", ... }, ...fields }
]
```

Now you can use the `feedback` object returned for the future [Search Feedback](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/search-feedback.md) request


```js
const { code, response, time } = await lablebClient.search(options);

const searchResults = response.results;

// later on, the end user clicks on the first result
const userInteraction = searchResults[0];

await lablebClient.feedback.search.single({
  documentFeedback: userInteraction.feedback
});
```



##### Facets Example

For details on each property check [Facets Anatomy](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/facets.md)

```json
{
    "count": 3,
    "language": {
        "buckets": [
            {
                "value": "ar",
                "count": 199
            },
            {
                "value": "en",
                "count": 199
            }
        ]
    },
    "categories": {
        "buckets": [
            {
                "value": "Accessories",
                "count": 37
            },
            {
                "value": "Hats ",
                "count": 252
            },
            ...
        ]
    },
    "status": {
        "buckets": [
            {
                "value": "Out Of Stock",
                "count": 194
            },
            {
                "value": "In Stock",
                "count": 5
            }
        ]
    }
}
```