# 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](/resources/document-search/full-text-search/create-a-search-index.md) 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*](/resources/apis.md)
{% 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="/files/83gQ1PeyFaYIvDKEVD5y" 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cosmocloud.io/templates/entity-search-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.