Search Service API

updated: 'Thu Jun 15 16:35:52 2017, commit e126d55'

Search Service API¶

Search¶

Provides indexing and search capabilities across OpenStack resources.

General information¶

The OpenStack Searchlight project provides a Search API that presents an interface for querying about the various resources available in an OpenStack cloud. Searchlight creates an index (using open source Elasticsearch technology) and keeps it updated. Additionally, Searchlight’s Search API requires authentication and respects the Role Based Access Control defined by each OpenStack service. This gives end users access to the powerful searching facilities provided by Elasticsearch, but operators can rest assured that end users won’t have access to information they wouldn’t be able to find in the APIs exposed by each of the OpenStack services.

The Search API allows you to construct detailed queries using the Elasticsearch Query Domain Specific Language. That’s great if you are an Elasticsearch expert (or want to become one), but is probably beyond what most end users need in order to use the Search API effectively. So we’ll provide a wide range of useful query examples below (see Create a general search).

To make effective use of the Search API, you need to know a few things about OpenStack resource types, how Searchlight stores data about OpenStack resources, and something about Searchlight plugins.

OpenStack resource types¶

An OpenStack cloud offers users many resources, for example, servers, images, networks. In order to eliminate ambiguity (for example, sometimes a resource you create with Nova is called a “server”, sometimes it’s called an “instance”), a standard vocabulary has developed based around that used by the OpenStack Heat project.

Heat identifies specific resource types that are assigned identifiers of the form

OS::{project_name}::{resource}

where {project_name} and {resource} are replaced by an actual project name and resource name. For example, a Nova server (or “instance”) has the resource type identifier OS::Nova::Server.

A list of OpenStack resource type identifiers is maintained by the Heat project at OpenStack Resource Types.

To summarize, you need to know the identifier for each OpenStack resource type you’re interested in so that you can efficiently search for those resources.

Searchlight data¶

Searchlight creates a document to represent each individual item (server, image, network) in an OpenStack cloud. These documents are stored in an Elasticsearch index. When you make a query using the Search API, the documents appropriate to your query (and your RBAC roles) are returned to you.

To facilitate searching, each document has a document type. Searchlight uses the OpenStack resource type (described in the previous section) as the document type. For example, a virtual machine image stored in Glance would be represented by a document with the document type OS::Glance::Image.

The particular document that corresponds to an individual OpenStack resource requires a unique identifier. It just so happens that each OpenStack service already assigns a unique identifier to each individual resource it controls, so that’s what Searchlight assigns as the document ID. For example, if you have an image in Glance with ID 997ec7e8-a46b-4ab7-a1d4-788e06f52abe, then that image will be represented in the index by a document with a document ID of 997ec7e8-a46b-4ab7-a1d4-788e06f52abe.

The information in the document will be the same content that would be available to you if you queried the native API that handles that particular resource type. For example, a document with document type OS::Glance::Image will contain the same information about an image as you would receive if you queried the Images API for information about that image. The advantage to using Searchlight, of course, is that you have access to advanced searching facilities provided by Elasticsearch.

Searchlight index¶

In the previous section, you learned that each document stored in Elasticsearch is uniquely identified by (a) what index it’s in, (b) what document type it has, and (c) what its document ID is. You already know how to determine the document type (it’s the resource type of the OpenStack resource you’re interested in) and the document ID (it’s the same as the identifier assigned to the resource by the OpenStack service that manages that resource). So what’s left is to figure out what index to use.

Due to careful engineering by top professionals, that’s pretty easy. Searchlight maintains its own index named ‘searchlight’. Further, the Search API automatically uses this index, so you don’t need to specify it. We only mention it here because you’ll see its name in some Elasticsearch responses that you’ll receive from the Search API, so it’s worth knowing what it is.

Note

The situation is actually a bit more complicated than we just portrayed it, so in the spirit of full disclosure, here are a few points to keep in mind:

Indices are transient, since a new one is created whenever Searchlight is re-indexed. The name of the index is described below, but a timestamp is appended to the name. All accesses to Elasticsearch are done through aliases and not directly through an index. For more details on aliases see the List plugins call.
By default, Searchlight uses a single index named ‘searchlight’. An operator, however, may choose to use a different name. Further, an operator may choose to have different resource types indexed into different indices so that, for example, “OS::Cinder::Volume” can have one Elasticsearch index, “OS::Neutron::Net” can have a different Elasticsearch index and “OS::Neutron::SecurityGroup” can have a third separate Elasticsearch index. But a default installation will use a single ‘searchlight’ index.
For architectural reasons (primarily to allow zero-downtime re-indexing), Searchlight doesn’t refer to the index directly, but instead uses index aliases. The key impact this has on you as a consumer of the API is that you’ll see references to aliases, instead of directly to the index, in some Search API responses.

One final point. Searchlight accomplishes its magic by using plugins that understand and index particular OpenStack resource types. So in order for a resource type to be accessible via the Search API, there must be a Searchlight plugin installed to index that kind of resource. Not all OpenStack resources currently have Searchlight plugins associated with them, and not all OpenStack deployers may have installed all available plugins. You can determine what’s available in a particular cloud by using the List plugins call.

GET

/v1/search/plugins

List plugins

List the supported plugins.

In order to index OpenStack resources, Searchlight requires a plugin specific to each resource type. Hence, the only resources that can be indexed in a particular OpenStack cloud are those for which (a) a plugin exists, and (b) the plugin is enabled by the cloud operator. You use this call to determine what document types you can expect to be able to search in a particular cloud.

Success¶

Code	Reason
`200 - OK`	The response contains an entity corresponding to the requested resource.

Error¶

Code	Reason
`400 - Bad Request`	The server cannot (or will not) process the request due to a client error.
`401 - Unauthorized`	You have either forgotten to provide credentials, or the credentials you provided are malformed or expired.
`403 - Forbidden`	You do not have sufficient permissions to perform the requested action.
`500 - Internal Server Error`	The server encountered an unexpected condition which prevented it from fulfilling the request.

Request¶

There are no request parameters, and this call does not take a request body.

Response¶

Name In Type Description

plugins

body

array

Name	In	Type	Description
plugins	body	array	List of plugins. Each element of the list contains the following fields: `alias-indexing` - the alias this plugin uses to refer to the Elasticsearch index in which documents are created `alias-searching` - the alias this plugin uses to refer to the Elasticsearch index used for querying documents created by this plugin `type` - the document type associated with this plugin

List of plugins. Each element of the list contains the following fields:

alias-indexing - the alias this plugin uses to refer to the Elasticsearch index in which documents are created
alias-searching - the alias this plugin uses to refer to the Elasticsearch index used for querying documents created by this plugin
type - the document type associated with this plugin

Response Example¶

{
    "plugins": [
        {
             "type": "OS::Glance::Image",
             "alias-indexing": "searchlight-listener",
             "alias-searching": "searchlight-search"
        },
        {
             "type": "OS::Glance::Metadef",
             "alias-indexing": "searchlight-listener",
             "alias-searching": "searchlight-search"
        }
    ]
}

List the supported facets.

For each registered resource type, Searchlight can provide a list of field names and values present for those fields.

Which fields are returned and whether values are listed is determined by each plugin.
Some fields or values may only be listed for administrative users.
For some string fields, facet_field may be included in the result. If present, it can be used to do an exact term match against facet options.

Success¶

Code	Reason
`200 - OK`	The response contains an entity corresponding to the requested resource.

Error¶

Code	Reason
`400 - Bad Request`	The server cannot (or will not) process the request due to a client error.
`401 - Unauthorized`	You have either forgotten to provide credentials, or the credentials you provided are malformed or expired.
`403 - Forbidden`	You do not have sufficient permissions to perform the requested action.
`500 - Internal Server Error`	The server encountered an unexpected condition which prevented it from fulfilling the request.

Request¶

Name	In	Type	Description
exclude_options (Optional)	query	boolean	Disable aggregating facet fields. Provides a performance improvement. The default value is `false`.
include_fields (Optional)	query	boolean	Disable showing the facet fields. Display count only. The default value is `true`.
type (Optional)	query	string	The resource type whose facets you’d like to see listed.

This call does not take a request body.

Response¶

Name	In	Type	Description
facets	body	object	A JSON object pairing resource type names with a list of facets supported for that resource type. Each facet object in the list contains the following fields: name - the name of the facet type - the datatype of the facet facet_field - (optional, may be available for some string fields) may be used to do an exact term match

Name

Type

Description

facets

body

object

A JSON object pairing resource type names with a list of facets supported for that resource type. Each facet object in the list contains the following fields:

name - the name of the facet
type - the datatype of the facet
facet_field - (optional, may be available for some string fields) may be used to do an exact term match

Response Example¶

{
    "OS::Glance::Image": {
        "doc_count": 50,
        "facets": [
            {
                "name": "status",
                "type": "string",
                "options": [
                    {
                        "key": "queued",
                        "doc_count": 47
                    },
                    {
                        "key": "active",
                        "doc_count": 3
                    }
                ]
            },
            {
                "name": "created_at",
                "type": "date"
            },
            {
                "name": "virtual_size",
                "type": "long"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
            { "...": "..." }
        ]
    },
    "OS::Glance::Metadef": {
        "doc_count": 25,
        "facets": [
            {
                "name": "objects.description",
                "nested": true,
                "type": "string"
            },
            {
                "name": "objects.properties.description",
                "nested": true,
                "type": "string"
            },
            { "...": "..." }
        ]
    },
    "OS::Nova::Server": {
        "doc_count": 100,
        "facets": [
            {
                "name": "status",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "ACTIVE"
                    }
                ],
                "type": "string"
            },
            {
                "name": "OS-EXT-SRV-ATTR:host",
                "type": "string"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
            {
                "name": "image.id",
                "type": "string"
            },
            {
                "name": "OS-EXT-AZ:availability_zone",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "nova"
                    }
                ],
                "type": "string"
            },
            { "...": "..." }
        ]
    }
}

Response Example (including `exclude_options` query parameter)¶

Assume this request: GET /v1/search/facets?exclude_options=true

{
    "OS::Glance::Image": {
        "doc_count": 50,
        "facets": [
            {
                "name": "status",
                "type": "string"
            },
            {
                "name": "created_at",
                "type": "date"
            },
            {
                "name": "virtual_size",
                "type": "long"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
            { "...": "..." }
        ]
    },
    "OS::Glance::Metadef": {
        "doc_count": 25,
        "facets": [
            {
                "name": "objects.description",
                "type": "string"
            },
            {
                "name": "objects.properties.description",
                "type": "string"
            },
            { "...": "..." }
        ]
    },
    "OS::Nova::Server": {
        "doc_count": 100,
        "facets": [
            {
                "name": "status",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "ACTIVE"
                    }
                ],
                "type": "string"
            },
            {
                "name": "OS-EXT-SRV-ATTR:host",
                "type": "string"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
            {
                "name": "image.id",
                "type": "string"
            },
            {
                "name": "OS-EXT-AZ:availability_zone",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "nova"
                    }
                ],
                "type": "string"
            },
            { "...": "..." }
        ]
    }
}

Response Example (including `type` query parameter)¶

Assume this request: GET /v1/search/facets?type=OS::Nova::Server

{
    "OS::Nova::Server": {
        "doc_count": 100,
        "facets": [
            {
                "name": "status",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "ACTIVE"
                    }
                ],
                "type": "string"
            },
            {
                "name": "OS-EXT-SRV-ATTR:host",
                "type": "string"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
           { "...": "..." }
        ]
    }
}

Response Example (including `include_fields` query parameter)¶

Assume this request: GET /v1/search/facets?include_fields=false

{
    "OS::Nova::Server": {
        "doc_count": 7
    },
    "OS::Neutron::Net": {
        "doc_count": 19
    },
    "OS::Glance::Image": {
        "doc_count": 68
    }
}

POST

/v1/search

Create a general search

Submit a search request.

Success¶

Code	Reason
`200 - OK`	The response contains an entity corresponding to the requested resource.

Error¶

Code	Reason
`400 - Bad Request`	The server cannot (or will not) process the request due to a client error.
`401 - Unauthorized`	You have either forgotten to provide credentials, or the credentials you provided are malformed or expired.
`403 - Forbidden`	You do not have sufficient permissions to perform the requested action.
`500 - Internal Server Error`	The server encountered an unexpected condition which prevented it from fulfilling the request.

Request¶

Name	In	Type	Description
Content-type	header	string	Mime type of the request body. Must be `application/json`.
query	body	object	A JSON object containing the requested query, expressed in the Elasticsearch Query DSL.

Request Example¶

{
    "query": {
        "match_all": {}
    }
}

Response¶

Name	In	Type	Description
_shards	body	object	A JSON object containing the following fields: `failed` - Number of shards in which the search could not be performed `successful` - Number of shards in which the search was successful `total` - The total number of shards involved in processing the query
hits	body	object	A JSON object containing the search results. It contains the following fields: `hits` - An array of search results (defaults to the first 25 documents). Each element of the array contains the following fields: `_id` - Uniquely identifies the resource within its OpenStack context (for instance, Glance images use their Image ID) `_index` - The service to which the resource belongs (for example, searchlight) `_score` - The relevance of a given hit. By default, this is the field upon which results are sorted `_source` - The document originally indexed, containing all data associated with the OpenStack resource. This field is a map, where each key is a field whose value may be a scalar value, a list, a nested object, or a list of nested objects. `_type` - The OpenStack resource type of the document (for example, “OS::Neutron::Net”, “OS::Glance::Image”) `_parent` - (optional) When the resource type has a child relationship to another resource type, the id of the specific parent resource will appear here. `_routing` - (optional) Included when an Elasticsearch routing for the document is explicitly specified. `max_score` - The highest `_score` of any document that matches the query `total` - The total number of documents matching the search criteria
timed_out	body	boolean	Indicates whether the search timed out or not.
took	body	number	The time in milliseconds it took for Elasticsearch to execute the search.

Response Example¶

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "OS::Software::DBMS",
                "_index": "searchlight",
                "_type": "OS::Glance::Metadef",
                "_score": 1.0,
                "_source": {
                    "description": "A database is an ...",
                    "display_name": "Database Software",
                    "namespace": "OS::Software::DBMS",
                    "objects": [
                        {
                            "description": "PostgreSQL, often simply 'Postgres' ...",
                            "name": "PostgreSQL",
                            "properties": [
                                {
                                    "default": "5432",
                                    "description": "Specifies the TCP/IP port...",
                                    "property": "sw_database_postgresql_listen_port",
                                    "...": "..."
                                },
                                { "...": "..." }
                            ]
                        }
                    ],
                    "tags": [
                        {
                            "name": "Database"
                        }
                    ]
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

POST

/v1/search

Create a type restricted search

Request a type restricted search.

By including a type field in your request, you can restrict the results to a particular resource type or types.

The type field can take either a string value (the name of a particular resource type) or an array of values (where each value is the name of a resource type).

Success¶

Code	Reason
`200 - OK`	The response contains an entity corresponding to the requested resource.

Error¶

Code	Reason
`400 - Bad Request`	The server cannot (or will not) process the request due to a client error.
`401 - Unauthorized`	You have either forgotten to provide credentials, or the credentials you provided are malformed or expired.
`403 - Forbidden`	You do not have sufficient permissions to perform the requested action.
`500 - Internal Server Error`	The server encountered an unexpected condition which prevented it from fulfilling the request.

Request¶

Name	In	Type	Description
Content-type	header	string	Mime type of the request body. Must be `application/json`.
query	body	object	A JSON object containing the requested query, expressed in the Elasticsearch Query DSL.
type	body	string or array of strings	The name of the resource type or types to which the search should be restricted.

Request Example (single resource type)¶

This example illustrates a request for a single resource type, Glance images.

{
    "query": {
        "match_all": {}
    },
    "type": "OS::Glance::Image"
}

Request Example (multiple resource types)¶

This example illustrates a request for multiple resource types, Glance images and Glance metadefs.

{
    "query": {
        "match_all": {}
    },
    "type": ["OS::Glance::Image", "OS::Glance::Metadef"]
}

Response¶

Name	In	Type	Description
_shards	body	object	A JSON object containing the following fields: `failed` - Number of shards in which the search could not be performed `successful` - Number of shards in which the search was successful `total` - The total number of shards involved in processing the query
hits	body	object	A JSON object containing the search results. It contains the following fields: `hits` - An array of search results (defaults to the first 25 documents). Each element of the array contains the following fields: `_id` - Uniquely identifies the resource within its OpenStack context (for instance, Glance images use their Image ID) `_index` - The service to which the resource belongs (for example, searchlight) `_score` - The relevance of a given hit. By default, this is the field upon which results are sorted `_source` - The document originally indexed, containing all data associated with the OpenStack resource. This field is a map, where each key is a field whose value may be a scalar value, a list, a nested object, or a list of nested objects. `_type` - The OpenStack resource type of the document (for example, “OS::Neutron::Net”, “OS::Glance::Image”) `_parent` - (optional) When the resource type has a child relationship to another resource type, the id of the specific parent resource will appear here. `_routing` - (optional) Included when an Elasticsearch routing for the document is explicitly specified. `max_score` - The highest `_score` of any document that matches the query `total` - The total number of documents matching the search criteria
timed_out	body	boolean	Indicates whether the search timed out or not.
took	body	number	The time in milliseconds it took for Elasticsearch to execute the search.

Response Example (single resource type)¶

This example illustrates the response to a request for a single resource type, Glance images (OS::Glance::Image).

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "a701f610-b162-45ac-a5a0-69e08aba8687",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "a701f610-b162-45ac-a5a0-69e08aba8687",
                    "members": [],
                    "name": "Docker container image",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

Response Example (multiple resource types)¶

This example illustrates the resonse to a request for multiple resource types, Glance images (OS::Glance::Image) and Glance metadefs (OS::Glance::Metadef).

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "OS::Software::DBMS",
                "_index": "searchlight",
                "_type": "OS::Glance::Metadef",
                "_score": 1.0,
                "_source": {
                    "description": "A database is an ...",
                    "display_name": "Database Software",
                    "namespace": "OS::Software::DBMS",
                    "objects": [
                        {
                            "description": "PostgreSQL, often simply 'Postgres' ...",
                            "name": "PostgreSQL",
                            "properties": [
                                {
                                    "default": "5432",
                                    "description": "Specifies the TCP/IP port...",
                                    "property": "sw_database_postgresql_listen_port",
                                    "...": "..."
                                },
                                { "...": "..." }
                            ]
                        }
                    ],
                    "tags": [
                        {
                            "name": "Database"
                        }
                    ]
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

POST

/v1/search

Create an administrative search

Submit an administrative search request.

By default, the results a user receives in a search response are limited to public resources and those resources owned by (or shared with) the user’s project (or “tenant”).

Administrators have the option to view all resources in the index by passing the all_projects field in the search request body.

Success¶

Code	Reason
`200 - OK`	The response contains an entity corresponding to the requested resource.

Error¶

Code	Reason
`400 - Bad Request`	The server cannot (or will not) process the request due to a client error.
`401 - Unauthorized`	You have either forgotten to provide credentials, or the credentials you provided are malformed or expired.
`403 - Forbidden`	You do not have sufficient permissions to perform the requested action.
`500 - Internal Server Error`	The server encountered an unexpected condition which prevented it from fulfilling the request.

Request¶

Name	In	Type	Description
Content-type	header	string	Mime type of the request body. Must be `application/json`.
query	body	object	A JSON object containing the requested query, expressed in the Elasticsearch Query DSL.
all_projects (Optional)	body	boolean	Indicates that an administator wants to include all resources for all projects in the search. The default is `false`.

Request Example¶

{
    "query": {
        "match_all": {}
    },
    "all_projects": true
}

Response¶

Name	In	Type	Description
_shards	body	object	A JSON object containing the following fields: `failed` - Number of shards in which the search could not be performed `successful` - Number of shards in which the search was successful `total` - The total number of shards involved in processing the query
hits	body	object	A JSON object containing the search results. It contains the following fields: `hits` - An array of search results (defaults to the first 25 documents). Each element of the array contains the following fields: `_id` - Uniquely identifies the resource within its OpenStack context (for instance, Glance images use their Image ID) `_index` - The service to which the resource belongs (for example, searchlight) `_score` - The relevance of a given hit. By default, this is the field upon which results are sorted `_source` - The document originally indexed, containing all data associated with the OpenStack resource. This field is a map, where each key is a field whose value may be a scalar value, a list, a nested object, or a list of nested objects. `_type` - The OpenStack resource type of the document (for example, “OS::Neutron::Net”, “OS::Glance::Image”) `_parent` - (optional) When the resource type has a child relationship to another resource type, the id of the specific parent resource will appear here. `_routing` - (optional) Included when an Elasticsearch routing for the document is explicitly specified. `max_score` - The highest `_score` of any document that matches the query `total` - The total number of documents matching the search criteria
timed_out	body	boolean	Indicates whether the search timed out or not.
took	body	number	The time in milliseconds it took for Elasticsearch to execute the search.

Response Example¶

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "OS::Software::DBMS",
                "_index": "searchlight",
                "_type": "OS::Glance::Metadef",
                "_score": 1.0,
                "_source": {
                    "description": "A database is an ...",
                    "display_name": "Database Software",
                    "namespace": "OS::Software::DBMS",
                    "objects": [
                        {
                            "description": "PostgreSQL, often simply 'Postgres' ...",
                            "name": "PostgreSQL",
                            "properties": [
                                {
                                    "default": "5432",
                                    "description": "Specifies the TCP/IP port...",
                                    "property": "sw_database_postgresql_listen_port",
                                    "...": "..."
                                },
                                { "...": "..." }
                            ]
                        }
                    ],
                    "tags": [
                        {
                            "name": "Database"
                        }
                    ]
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

POST

/v1/search

Create a free text search

Submit a free text search request.

Success¶

Code	Reason
`200 - OK`	The response contains an entity corresponding to the requested resource.

Error¶

Code	Reason
`400 - Bad Request`	The server cannot (or will not) process the request due to a client error.
`401 - Unauthorized`	You have either forgotten to provide credentials, or the credentials you provided are malformed or expired.
`403 - Forbidden`	You do not have sufficient permissions to perform the requested action.
`500 - Internal Server Error`	The server encountered an unexpected condition which prevented it from fulfilling the request.

Request¶

Name	In	Type	Description
Content-type	header	string	Mime type of the request body. Must be `application/json`.
type	body	string or array of strings	The name of the resource type or types to which the search should be restricted.
multi_match	body	string or array of strings	A JSON object containing a `query` field whose value is an Elasticsearch query string.

Request Example¶

Suppose you want to find all images that have the word “cirros” in some field, whether the in the name, tags, or any other image properties.

{
    "type": "OS::Glance::Image",
    "query": {
        "multi_match": {
            "query":"cirros",
            "fields": ["_all"]
        }
    }
}

Response¶

Name	In	Type	Description
_shards	body	object	A JSON object containing the following fields: `failed` - Number of shards in which the search could not be performed `successful` - Number of shards in which the search was successful `total` - The total number of shards involved in processing the query
hits	body	object	A JSON object containing the search results. It contains the following fields: `hits` - An array of search results (defaults to the first 25 documents). Each element of the array contains the following fields: `_id` - Uniquely identifies the resource within its OpenStack context (for instance, Glance images use their Image ID) `_index` - The service to which the resource belongs (for example, searchlight) `_score` - The relevance of a given hit. By default, this is the field upon which results are sorted `_source` - The document originally indexed, containing all data associated with the OpenStack resource. This field is a map, where each key is a field whose value may be a scalar value, a list, a nested object, or a list of nested objects. `_type` - The OpenStack resource type of the document (for example, “OS::Neutron::Net”, “OS::Glance::Image”) `_parent` - (optional) When the resource type has a child relationship to another resource type, the id of the specific parent resource will appear here. `_routing` - (optional) Included when an Elasticsearch routing for the document is explicitly specified. `max_score` - The highest `_score` of any document that matches the query `total` - The total number of documents matching the search criteria
timed_out	body	boolean	Indicates whether the search timed out or not.
took	body	number	The time in milliseconds it took for Elasticsearch to execute the search.

Response Example¶

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "15c2501d-07bd-4eb1-b15f-77ef739e5419",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "15c2501d-07bd-4eb1-b15f-77ef739e5419",
                    "description": "Extra special cirros image",
                    "members": [],
                    "name": "Simply Sensational",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

POST

/v1/search

Create a phrase search

Submit a search request that looks for a phrase in a particular field.

A common scenario is that you have custom metadata on some resources describing the resource in natural language. For example, you may have set a property named description on your images, where the value is a natural language sentence describing the recommended uses for that image. You can query the Search API for responses that match that phrase in that field.

Success¶

Code	Reason
`200 - OK`	The response contains an entity corresponding to the requested resource.

Error¶

Code	Reason
`400 - Bad Request`	The server cannot (or will not) process the request due to a client error.
`401 - Unauthorized`	You have either forgotten to provide credentials, or the credentials you provided are malformed or expired.
`403 - Forbidden`	You do not have sufficient permissions to perform the requested action.
`500 - Internal Server Error`	The server encountered an unexpected condition which prevented it from fulfilling the request.

Request¶

Suppose you use a description property on images as described above, and you are interested in finding any images that are described as “Preconfigured with a schmaltz to optimize the foobar.”

Name	In	Type	Description
Content-type	header	string	Mime type of the request body. Must be `application/json`.
query	body	object	A JSON object containing the requested query, expressed in the Elasticsearch Query DSL.

Request Example¶

{
    "type": "OS::Glance::Image",
    "query": {
        "match_phrase": {
            "description": "Preconfigured with a schmaltz to optimize the foobar"
        }
    }
}

Response¶

Name	In	Type	Description
_shards	body	object	A JSON object containing the following fields: `failed` - Number of shards in which the search could not be performed `successful` - Number of shards in which the search was successful `total` - The total number of shards involved in processing the query
hits	body	object	A JSON object containing the search results. It contains the following fields: `hits` - An array of search results (defaults to the first 25 documents). Each element of the array contains the following fields: `_id` - Uniquely identifies the resource within its OpenStack context (for instance, Glance images use their Image ID) `_index` - The service to which the resource belongs (for example, searchlight) `_score` - The relevance of a given hit. By default, this is the field upon which results are sorted `_source` - The document originally indexed, containing all data associated with the OpenStack resource. This field is a map, where each key is a field whose value may be a scalar value, a list, a nested object, or a list of nested objects. `_type` - The OpenStack resource type of the document (for example, “OS::Neutron::Net”, “OS::Glance::Image”) `_parent` - (optional) When the resource type has a child relationship to another resource type, the id of the specific parent resource will appear here. `_routing` - (optional) Included when an Elasticsearch routing for the document is explicitly specified. `max_score` - The highest `_score` of any document that matches the query `total` - The total number of documents matching the search criteria
timed_out	body	boolean	Indicates whether the search timed out or not.
took	body	number	The time in milliseconds it took for Elasticsearch to execute the search.

Response Example¶

{
  "hits": {
    "hits": [
      {
        "_score": 12.945373,
        "_type": "OS::Glance::Image",
        "_id": "7a99b58d-0b70-4138-8086-ab0cc4bd1ba3",
        "_source": {
          "container_format": "bare",
          "min_ram": 0,
          "updated_at": "2016-08-25T17:54:02Z",
          "cim_pasd_processorarchitecture": "Power",
          "owner": "158776c9face41a7a3026d6c1cae686a",
          "id": "7a99b58d-0b70-4138-8086-ab0cc4bd1ba3",
          "size": 5969,
          "image_type": "image",
          "disk_format": "raw",
          "project_id": "158776c9face41a7a3026d6c1cae686a",
          "status": "active",
          "description": "Preconfigured with a schmaltz to optimize the foobar",
          "tags": [],
          "hw_cpu_policy": "shared",
          "visibility": "public",
          "members": [],
          "min_disk": 0,
          "virtual_size": null,
          "name": "My Awesome Image",
          "checksum": null,
          "created_at": "2016-08-25T17:54:02Z",
          "protected": false
        },
        "_index": "searchlight-2016_08_25_18_48_30"
      }
    ],
    "total": 1,
    "max_score": 12.945373
  },
  "_shards": {
    "successful": 1,
    "failed": 0,
    "total": 1
  },
  "took": 4,
  "timed_out": false
}

POST

/v1/search

Create a compound boolean search

Submit a compound boolean search request.

Success¶

Code	Reason
`200 - OK`	The response contains an entity corresponding to the requested resource.

Error¶

Code	Reason
`400 - Bad Request`	The server cannot (or will not) process the request due to a client error.
`401 - Unauthorized`	You have either forgotten to provide credentials, or the credentials you provided are malformed or expired.
`403 - Forbidden`	You do not have sufficient permissions to perform the requested action.
`500 - Internal Server Error`	The server encountered an unexpected condition which prevented it from fulfilling the request.

Request¶

Name	In	Type	Description
Content-type	header	string	Mime type of the request body. Must be `application/json`.
query	body	object	A JSON object containing the requested query, expressed in the Elasticsearch Query DSL.

Request Example¶

Suppose you want to find all the images that meet the following set of conditions:

The image must be public and active. (This is a must clause.)
The image cannot require more than 4096 RAM. (This is a must_not clause with a range query.)
The image must not be aki or ari. (This is a must_not clause)
Either the name or the tags should contain “cirros”. (This is a should clause with minimum match of 1.)
In the results, indicate (“highlight”) why these results were included in the request.

{
    "type": "OS::Glance::Image",
    "query": {
        "bool" : {
            "must" : [
                { "term" : { "status" : "active" } },
                { "term" : { "visibility" : "public" } }
            ],
            "must_not" : [
                { "range" : { "min_ram" : { "gt" : 4096 } } },
                { "terms" : { "disk_format" : ["aki", "ari"] } }
            ],
            "should" : [
                { "match" : { "name" : "cirros" } },
                { "match" : { "tag" : "cirros" } }
            ],
            "minimum_should_match" : 1
        }
    },
    "highlight": {
       "fields": {
          "*":{}
       }
   }
}

Response¶

Name	In	Type	Description
_shards	body	object	A JSON object containing the following fields: `failed` - Number of shards in which the search could not be performed `successful` - Number of shards in which the search was successful `total` - The total number of shards involved in processing the query
hits	body	object	A JSON object containing the search results. It contains the following fields: `hits` - An array of search results (defaults to the first 25 documents). Each element of the array contains the following fields: `_id` - Uniquely identifies the resource within its OpenStack context (for instance, Glance images use their Image ID) `_index` - The service to which the resource belongs (for example, searchlight) `_score` - The relevance of a given hit. By default, this is the field upon which results are sorted `_source` - The document originally indexed, containing all data associated with the OpenStack resource. This field is a map, where each key is a field whose value may be a scalar value, a list, a nested object, or a list of nested objects. `_type` - The OpenStack resource type of the document (for example, “OS::Neutron::Net”, “OS::Glance::Image”) `_parent` - (optional) When the resource type has a child relationship to another resource type, the id of the specific parent resource will appear here. `_routing` - (optional) Included when an Elasticsearch routing for the document is explicitly specified. `max_score` - The highest `_score` of any document that matches the query `total` - The total number of documents matching the search criteria
timed_out	body	boolean	Indicates whether the search timed out or not.
took	body	number	The time in milliseconds it took for Elasticsearch to execute the search.

Response Example¶

{
  "hits": {
    "hits": [
      {
        "_type": "OS::Glance::Image",
        "_source": {
          "status": "active",
          "created_at": "2016-08-25T17:32:41Z",
          "project_id": "98c05407d80c405aa6efa01b279385ce",
          "name": "cirros-0.3.4-x86_64-uec",
          "tags": [],
          "image_type": "image",
          "checksum": "eb9139e4942121f22bbc2afc0400b2a4",
          "min_ram": 0,
          "ramdisk_id": "f310fb51-29dc-47bf-8cbd-3ea1170fb4e3",
          "disk_format": "ami",
          "updated_at": "2016-08-25T17:32:42Z",
          "visibility": "public",
          "kernel_id": "34ddf1d2-b588-4a9a-a3d3-344768c04bfd",
          "protected": false,
          "members": [],
          "container_format": "ami",
          "min_disk": 0,
          "owner": "98c05407d80c405aa6efa01b279385ce",
          "virtual_size": null,
          "id": "23fa3971-3ed8-435a-a3c6-8addea5153aa",
          "size": 25165824
        },
        "_score": 3.3642778,
        "_index": "searchlight-2016_08_25_18_48_30",
        "highlight": {
          "status": [
            "<em>active</em>"
          ],
          "name": [
            "<em>cirros</em>-0.3.4-x86_64-uec"
          ],
          "visibility": [
            "<em>public</em>"
          ]
        },
        "_id": "23fa3971-3ed8-435a-a3c6-8addea5153aa"
      },
      {
        "_type": "OS::Glance::Image",
        "_source": {
          "status": "active",
          "created_at": "2016-08-25T17:32:34Z",
          "project_id": "98c05407d80c405aa6efa01b279385ce",
          "name": "cirros-0.3.4-x86_64-disk",
          "tags": [],
          "image_type": "image",
          "checksum": "ee1eca47dc88f4879d8a229cc70a07c6",
          "min_ram": 0,
          "disk_format": "qcow2",
          "updated_at": "2016-08-25T17:32:35Z",
          "visibility": "public",
          "owner": "98c05407d80c405aa6efa01b279385ce",
          "protected": false,
          "members": [],
          "container_format": "bare",
          "min_disk": 0,
          "virtual_size": null,
          "id": "f34de38c-7a5c-4b00-8015-70a7a63480e8",
          "size": 13287936
        },
        "_score": 3.3642778,
        "_index": "searchlight-2016_08_25_18_48_30",
        "highlight": {
          "status": [
            "<em>active</em>"
          ],
          "name": [
            "<em>cirros</em>-0.3.4-x86_64-disk"
          ],
          "visibility": [
            "<em>public</em>"
          ]
        },
        "_id": "f34de38c-7a5c-4b00-8015-70a7a63480e8"
      }
    ],
    "total": 2,
    "max_score": 3.3642778
  },
  "_shards": {
    "successful": 1,
    "failed": 0,
    "total": 1
  },
  "took": 1,
  "timed_out": false
}

POST

/v1/search

Create an aggregated search

Submit an aggregated search request.

Success¶

Code	Reason
`200 - OK`	The response contains an entity corresponding to the requested resource.

Error¶

Code	Reason
`400 - Bad Request`	The server cannot (or will not) process the request due to a client error.
`401 - Unauthorized`	You have either forgotten to provide credentials, or the credentials you provided are malformed or expired.
`403 - Forbidden`	You do not have sufficient permissions to perform the requested action.
`500 - Internal Server Error`	The server encountered an unexpected condition which prevented it from fulfilling the request.

Request¶

Name	In	Type	Description
Content-type	header	string	Mime type of the request body. Must be `application/json`.
query	body	object	A JSON object containing the requested query, expressed in the Elasticsearch Query DSL.

Request Example¶

Suppose you want to find a count of the different names and container_formats in all images.

{
    "query": {
        "match_all": {}
    },
    "type": ["OS::Glance::Image"],
    "limit": 0,
    "aggregations": {
        "name": {"terms": {"field": "name"}},
        "container_format": {"terms": {"field": "container_format"}}
    }
}

Response¶

Name	In	Type	Description
_shards	body	object	A JSON object containing the following fields: `failed` - Number of shards in which the search could not be performed `successful` - Number of shards in which the search was successful `total` - The total number of shards involved in processing the query
hits	body	object	A JSON object containing the search results. It contains the following fields: `hits` - An array of search results (defaults to the first 25 documents). Each element of the array contains the following fields: `_id` - Uniquely identifies the resource within its OpenStack context (for instance, Glance images use their Image ID) `_index` - The service to which the resource belongs (for example, searchlight) `_score` - The relevance of a given hit. By default, this is the field upon which results are sorted `_source` - The document originally indexed, containing all data associated with the OpenStack resource. This field is a map, where each key is a field whose value may be a scalar value, a list, a nested object, or a list of nested objects. `_type` - The OpenStack resource type of the document (for example, “OS::Neutron::Net”, “OS::Glance::Image”) `_parent` - (optional) When the resource type has a child relationship to another resource type, the id of the specific parent resource will appear here. `_routing` - (optional) Included when an Elasticsearch routing for the document is explicitly specified. `max_score` - The highest `_score` of any document that matches the query `total` - The total number of documents matching the search criteria
aggregations	body	object	A JSON object containing the aggregation results. It contains the following fields: `buckets` - An array of aggregated results (defaults to the top ten terms). There is a bucket for each term. Each element of the array contains the following fields: `doc_count` - Number of times this term appears. `key` - The value of this term. `doc_count_error_upper_bound` - The upper bound on the error when compiling the document count, needed since the count is approximate. `sum_other_doc_count` - Since the number of elements in the bucket array may be capped (default is ten), the number of all other document counts not included in buckets.
timed_out	body	boolean	Indicates whether the search timed out or not.
took	body	number	The time in milliseconds it took for Elasticsearch to execute the search.

Response Example¶

{
    "_shards": {
        "successful": 1,
        "failed": 0,
        "total": 1
    },
    "aggregations": {
        "container_format": {
            "buckets": [
                {
                    "doc_count": 101,
                    "key": "bare"
                },
                {
                    "doc_count": 1,
                    "key": "aki"
                },
                {
                    "doc_count": 1,
                    "key": "ami"
                },
                {
                    "doc_count": 1,
                    "key": "ari"
                }
            ],
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0
        },
        "name": {
            "buckets": [
                {
                    "doc_count": 100,
                    "key": "image"
                },
                {
                    "doc_count": 3,
                    "key": "0.3.4"
                },
                {
                    "doc_count": 3,
                    "key": "cirros"
                },
                {
                    "doc_count": 3,
                    "key": "uec"
                },
                {
                    "doc_count": 3,
                    "key": "x86_64"
                }
            ],
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0
        }
    },
    "hits": {
        "hits": [],
        "max_score": 0.0,
        "total": 104
    },
    "took": 5,
    "timed_out": false
}

References¶

updated: 'Thu Jun 15 16:35:52 2017, commit e126d55'

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.