Search API

The Search API provides a way to search MongoDB databases, as long as your data is properly exposed to the Itential Platform search engine. This guide explains how to set indexes and expose your data collections using search objects.

Expose an application for searching

A database collection can be searched if it is exposed with a search object. This search object is added to the pronghorn.json file and consists of an object, or array of objects, following the schema below.

Search object attributes

Examples

Empty search template

1
"search": {
2
  "label": "YOUR APP NAME",
3
  "collection": "DATABASE COLLECTION NAME",
4
  "fields": [
5
    {
6
      "name": "FIELD TITLE",
7
      "type": "string"
8
    }
9
  ],
10
  "map": {
11
    "name": "FIELD REFERENCE NAME",
12
    "description": "FIELD REFERENCE NAME (can be null or empty)",
13
    "url": "/myapp/{{EXAMPLE_VAR}}?myvar={{EXAMPLE_VAR}}"
14
  }
15
}

Search exposure object

1
"search": {
2
  "label": "Mop",
3
  "collection": "mop_templates",
4
  "fields": [
5
    {
6
      "name": "name",
7
      "type": "string"
8
    }
9
  ],
10
  "map": {
11
    "name": "name",
12
    "description": null,
13
    "url": "/mop/template?name={{name}}"
14
  }
15
}

Currently, only text-based fields ("type": "string") are supported for searching.

Create an index for exposed collections

You must create the appropriate indexes for your fields to be search-enabled. MongoDB uses compound indexes — list each field name followed by 1 as the value.

The compound index must match the fields in the search template. For example, if you want to search on name and type, you must have a compound index on both fields.

To create an index against a local instance for testing, run the following in a MongoDB collection browser. This example creates an index on the MOP templates collection for name:

1
db.getCollection('mop_templates').createIndex({ "name": 1 }, { background: true });

Follow these guidelines when creating indexes:

• Avoid creating too many indexes. Excess indexes slow down inserts into the database.
• Always set background to true when creating indexes to support performance at scale.
• Test the addition of search objects in a lab environment to monitor performance before releasing to production.

Make a search request

The POST body consists of a data object with a text property containing the value to search for.

Empty request

1
{
2
    "data": {
3
        "text": "TEXT TO SEARCH ON"
4
    }
5
}

Search object example (searching for the word workflow):

1
{
2
    "data": {
3
        "text": "workflow"
4
    }
5
}

Search results

Results follow the map object configured above, with the addition of _id and tags fields:

1
{
2
    "results": [
3
        {
4
            "label": "Mop",
5
            "type": "mop_templates",
6
            "results": [
7
                {
8
                    "_id": "workflow helper",
9
                    "name": "workflow helper",
10
                    "description": "",
11
                    "url": "/mop/template?name=workflow%20helper",
12
                    "tags": [
13
                        {
14
                            "_id": "5c37ada0788ede01a2b62b47",
15
                            "name": "Awesome",
16
                            "description": "Sauce"
17
                        }
18
                    ]
19
                },
20
                {
21
                    "_id": "workflow helper two",
22
                    "name": "workflow helper two",
23
                    "description": "",
24
                    "url": "/mop/template?name=workflow%20helper%20two",
25
                    "tags": []
26
                }
27
            ],
28
            "count": 2
29
        },
30
        {
31
            "label": "Workflows",
32
            "type": "workflows",
33
            "results": [
34
                {
35
                    "_id": "51fdc757-076a-41d6-9e51-bf7856aabb28",
36
                    "name": "Delay Workflow",
37
                    "description": "",
38
                    "url": "/workflow_builder/edit?name=Delay%20Workflow",
39
                    "tags": []
40
                }
41
            ],
42
            "count": 1
43
        }
44
    ],
45
    "totalCount": 3
46
}

Top-level result fields

Result group fields

Individual search result fields

Currently supported Itential applications

The following Itential applications already have search objects and indexes configured:

Additional information

The Search REST API is currently used only by the site-wide search box in the top navigation bar. You can, however, use the results in your own application if needed.