# knife search

Search indexes allow queries to be made for any type of data that is indexed by the Chef server, including data bags (and data bag items), environments, nodes, and roles. A defined query syntax is used to support search patterns like exact, wildcard, range, and fuzzy. A search is a full-text query that can be done from several locations, including from within a recipe, by using the `search` subcommand in knife, the `search` method in the Recipe DSL, and by using the `/search` or `/search/INDEX` endpoints in the Chef server API. The search engine is based on Apache Solr and is run from the Chef server.

The knife search subcommand is used run a search query for information that is indexed on a Chef server.

## Syntax

This subcommand has the following syntax:

    $ knife search INDEX SEARCH_QUERY

where `INDEX` is one of `client`, `environment`, `node`, `role`, or the name of a data bag and `SEARCH_QUERY` is the search query syntax for the query that will be executed.

`INDEX` is implied if omitted, and will default to `node`. For example:

    $ knife search '*:*' -i

will return something similar to:

    8 items found

    centos-62-dev
    opensuse-1203
    ubuntu-1304-dev
    ubuntu-1304-orgtest
    ubuntu-1204-ohai-test
    ubuntu-1304-ifcfg-test
    ohai-test
    win2k8-dev

and is the same search as:

    $ knife search node '*:*" -i

If the `SEARCH_QUERY` does not contain a colon character (`:`), then the default query pattern is `tags:*#{@query}* OR roles:*#{@query}* OR fqdn:*#{@query}* OR addresses:*#{@query}*`, which means the following two search queries are effectively the same:

    $ knife search ubuntu

or:

    $ knife search node "tags:*ubuntu* OR roles:*ubuntu* OR fqdn:*ubuntu* (etc.)"

## Options

Note

Review the list of common options available to this (and all) knife subcommands and plugins.

This sub-command has the following options:

`-a ATTR`, `--attribute ATTR`
  The attribute (or attributes) to show.
`-b ROW`, `--start ROW`
  The row at which return results will begin.
`-i`, `--id-only`
  Use to show only matching object IDs.
`INDEX`
  The name of the index to be queried: `client`, `environment`, `node`, `role`, or `DATA_BAG_NAME`. Default index: `node`.
`-l`, `--long`
  Use to display all attributes in the output and to show the output as JSON.
`-m`, `--medium`
  Use to display normal attributes in the output and to show the output as JSON.
`-o SORT`, `--sort SORT`
  The order in which search results will be sorted.
`-q SEARCH_QUERY`, `--query SEARCH_QUERY`
  Use to protect search queries that start with a hyphen (-). A `-q` query may be specified as an argument or an option, but not both.
`-r`, `--run-list`
  Use to show only the run-list.
`-R INT`, `--rows INT`
  The number of rows to be returned.
`SEARCH_QUERY`
  The search query used to identify a a list of items on a Chef server. This option uses the same syntax as the `search` sub-command.

## Examples

The following examples show how to use this knife subcommand:

Search by platform ID

To search for the IDs of all nodes running on the Amazon EC2 platform, enter:

    $ knife search node 'ec2:*' -i

to return something like:

    4 items found

    ip-0A7CA19F.ec2.internal

    ip-0A58CF8E.ec2.internal

    ip-0A58E134.ec2.internal

    ip-0A7CFFD5.ec2.internal

Search by instance type

To search for the instance type (flavor) of all nodes running on the Amazon EC2 platform, enter:

    $ knife search node 'ec2:*' -a ec2.instance_type

to return something like:

    4 items found

    ec2.instance_type:  m1.large
    id:                 ip-0A7CA19F.ec2.internal

    ec2.instance_type:  m1.large
    id:                 ip-0A58CF8E.ec2.internal

    ec2.instance_type:  m1.large
    id:                 ip-0A58E134.ec2.internal

    ec2.instance_type:  m1.large
    id:                 ip-0A7CFFD5.ec2.internal

Search by node

To search for all nodes running Ubuntu, enter:

    $ knife search node 'platform:ubuntu'

Search by node and environment

To search for all nodes running CentOS in the production environment, enter:

    $ knife search node 'chef_environment:production AND platform:centos'

Search for nested attributes

To find a nested attribute, use a pattern similar to the following:

    $ knife search node <query_to_run> -a <main_attribute>.<nested_attribute>

Search for multiple attributes

To build a search query to use more than one attribute, use an underscore (`_`) to separate each attribute. For example, the following query will search for all nodes running a specific version of Ruby:

    $ knife search node "languages_ruby_version:1.9.3"

Search for nested attributes using a search query

To build a search query that can find a nested attribute:

    $ knife search node name:<node_name> -a kernel.machine

Use a test query

To test a search query that will be used in a knife ssh command:

    $ knife search node "role:web NOT name:web03"

where the query in the previous example will search all servers that have the `web` role, but not on the server named `web03`.