# Entity Search APIs

Entity Search APIs is a powerful feature that enables users to perform advanced search operations on their database entities using a specialised search index in MongoDB. This feature simplifies the development process and enhances user experience by providing:

* Fast and efficient retrieval of relevant data
* Optimised query performance
* Advanced search capabilities based on various criteria
* Simplified implementation of search functionality in applications

### Prerequisites

1. Created a Search Index in your database using either:
   * Cosmocloud's [Search Index](https://docs.cosmocloud.io/resources/document-search/full-text-search/create-a-search-index) feature
   * Manual configuration in your MongoDB database
2. Familiarity with your data structure and fields you want to search on

### Steps to create APIs from Template

1. Navigate to the APIs listing page from Application Layer -> APIs.
2. Click on the Create API button on the top right corner.
3. Select the Browse Template option from the dialogue box.
4. Select the Entity Search APIs option.
5. Configure the following settings:
   * Select your environment
   * Choose the previously created Search Index
   * Select query fields (fields to be searched)
   * Select filter fields (fields for which unique values will be returned)
6. Click on finish to generate the starter APIs and models.

{% hint style="info" %}
You can then customise and edit any APIs that are created via Templates

[*How to customise APIs*](https://docs.cosmocloud.io/resources/apis)
{% endhint %}

### Generated Components

* One API method: `_search`
* One Request Model

Initially, the API and the model will be created in `Draft` state. You can edit them in the Workflow builder to add more customisations.

### API Method: `_search`

* The `_search` method allows you to search fields based on the provided query.

#### Query Parameters:

| **Parameter** | **Description**                             | **Type** | **Required** |
| ------------- | ------------------------------------------- | -------- | ------------ |
| query         | Text to search on the selected query fields | String   | true         |
| limit         | Maximum number of records to return         | Number   | true         |
| offset        | Number of records to skip                   | Number   | true         |

#### Response

The API returns a JSON object containing:

* `data`: Array of matching records according to the query and selected query fields
* `count`: Total count of matching records
* `*_filters`: Sets of unique values for each selected filter field

  ```
  [
    {
        "data": [
            {
                "_id": "66a67446f6a373b76cae0c04",
                "title": "Complete Cosmocloud"
            },
            {
                "_id": "66a67585f6a373b76cb1ebe8",
                "title": "Try Cosmocloud"
            }
        ],
        "count": [
            {
                "totalCount": 2
            }
        ],
        "status_filters": [
            {
                "_id": null,
                "items": [
                    "PENDING",
                    "COMPLETE"
                ]
            }
        ]
    }
  ]
  ```

  In this example, the API was created with `title` as a query field, `status` as a filter field. The `query` value was `Cosmocloud`

<figure><img src="https://392607133-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZCdm9aJ8vkvDIIbg04AL%2Fuploads%2FDqsXFO3Ae2lbvR2Zgjmi%2FScreenshot%202024-07-28%20at%2010.35.25%E2%80%AFPM.png?alt=media&#x26;token=b9ead23c-6442-4819-b8b4-f38934d3813c" alt=""><figcaption><p>Search API</p></figcaption></figure>

### Best Practices

* Choose query fields wisely to balance search accuracy and performance.
* Implement pagination using `limit` and `offset` for better performance with large datasets.
* Regularly update your Search Index to reflect changes in your data structure.