1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "KNIFE\-SEARCH" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual"
.
.SH "NAME"
\fBknife\-search\fR \- Find objects on a Chef Server by query
.
.SH "SYNOPSIS"
\fBknife\fR \fBsearch INDEX QUERY\fR \fI(options)\fR
.
.TP
\fB\-a\fR, \fB\-\-attribute ATTR\fR
Show only one attribute
.
.TP
\fB\-i\fR, \fB\-\-id\-only\fR
Show only the ID of matching objects
.
.TP
\fB\-q\fR, \fB\-\-query QUERY\fR
The search query; useful to protect queries starting with \-
.
.TP
\fB\-R\fR, \fB\-\-rows INT\fR
The number of rows to return
.
.TP
\fB\-r\fR, \fB\-\-run\-list\fR
Show only the run list
.
.TP
\fB\-o\fR, \fB\-\-sort SORT\fR
The order to sort the results in
.
.TP
\fB\-b\fR, \fB\-\-start ROW\fR
The row to start returning results at
.
.TP
\fB\-m\fR, \fB\-\-medium\fR
Display medium sized output when searching nodes using the default summary format
.
.TP
\fB\-l\fR, \fB\-\-long\fR
Display long output when searching nodes using the default summary format
.
.SH "DESCRIPTION"
Search is a feature of the Chef Server that allows you to use a full\-text search engine to query information about your infrastructure and applications\. You can utilize this service via search calls in a recipe or the knife search command\. The search syntax is based on Lucene\.
.
.SH "INDEXES"
Search indexes are a feature of the Chef Server and the search sub\-command allows querying any of the available indexes using SOLR query syntax\. The following data types are indexed for search:
.
.IP "\(bu" 4
\fInode\fR
.
.IP "\(bu" 4
\fIrole\fR
.
.IP "\(bu" 4
\fIenvironment\fR
.
.IP "\(bu" 4
\fIclients\fR
.
.IP "\(bu" 4
\fIdata bag\fR
.
.IP "" 0
.
.P
Data bags are indexed by the data bag\'s name\. For example, to search a data bag named "admins":
.
.IP "" 4
.
.nf
knife search admins "field:search_pattern"
.
.fi
.
.IP "" 0
.
.SH "QUERY SYNTAX"
Queries have the form \fBfield:search_pattern\fR where \fBfield\fR is a key in the JSON description of the relevant objects (nodes, roles, environments, or data bags)\. Both \fBfield\fR and \fBsearch_pattern\fR are case\-sensitive\. \fBsearch_pattern\fR can be an exact, wildcard, range, or fuzzy match (see below)\. The \fBfield\fR supports exact matching and limited wildcard matching\.
.
.P
Searches will return the relevant objects (nodes, roles, environments, or data bags) where the \fBsearch_pattern\fR matches the object\'s value of \fBfield\fR\.
.
.SS "FIELD NAMES"
Field names are the keys within the JSON description of the object being searched\. Nested Keys can be searched by placing an underscore ("_") between key names\.
.
.SS "WILDCARD MATCHING FOR FIELD NAMES"
The field name also has limited support for wildcard matching\. Both the "*" and "?" wildcards (see below) can be used within a field name; however, they cannot be the first character of the field name\.
.
.SS "EXACT MATCHES"
Without any search modifiers, a search returns those fields for which the \fBsearch_pattern\fR exactly matches the value of \fBfield\fR in the JSON description of the object\.
.
.SS "WILDCARD MATCHES"
Search support both single\- and multi\-character wildcard searches within a search pattern\.
.
.P
\'?\' matches exactly one character\.
.
.P
\'*\' matches zero or more characters\.
.
.SS "RANGE MATCHES"
Range searches allows one to match values between two given values\. To match values between X and Y, inclusively, use square brackets:
.
.IP "" 4
.
.nf
knife search INDEX \'field:[X TO Y]
.
.fi
.
.IP "" 0
.
.P
To match values between X and Y, exclusively, use curly brackets:
.
.IP "" 4
.
.nf
knife search INDEX \'field:{X TO Y}\'
.
.fi
.
.IP "" 0
.
.P
Values are sorted in lexicographic order\.
.
.SS "FUZZY MATCHES"
Fuzzy searches allows one to match values based on the Levenshtein Distance algorithm\. To perform a fuzzy match, append a tilda (~) to the search term:
.
.IP "" 4
.
.nf
knife search INDEX \'field:term~\'
.
.fi
.
.IP "" 0
.
.P
This search would return nodes whose \fBfield\fR was \'perm\' or \'germ\'\.
.
.SS "BOOLEAN OPERATORS"
The boolean operators NOT, AND, and OR are supported\. To find values of \fBfield\fR that are not X:
.
.IP "" 4
.
.nf
knife search INDEX \'field:(NOT X)\'
.
.fi
.
.IP "" 0
.
.P
To find records where \fBfield1\fR is X and \fBfield2\fR is Y:
.
.IP "" 4
.
.nf
knife search INDEX \'field1:X AND field2:Y\'
.
.fi
.
.IP "" 0
.
.P
To find records where \fBfield\fR is X or Y:
.
.IP "" 4
.
.nf
knife search INDEX \'field:X OR field:Y\'
.
.fi
.
.IP "" 0
.
.SS "QUOTING AND SPECIAL CHARACTERS"
In order to avoid having special characters and escape sequences within your search term interpreted by either Ruby or the shell, enclose them in single quotes\.
.
.P
Search terms that include spaces should be enclosed in double\-quotes:
.
.IP "" 4
.
.nf
knife search INDEX \'field:"term with spaces"\'
.
.fi
.
.IP "" 0
.
.P
The following characters must be escaped:
.
.IP "" 4
.
.nf
+ \- && || ! ( ) { } [ ] ^ " ~ * ? : \e
.
.fi
.
.IP "" 0
.
.SH "EXAMPLES"
Find the nodes with the fully\-qualified domain name (FQDN) www\.example\.com:
.
.IP "" 4
.
.nf
knife search node \'fqdn:www\.example\.com\'
.
.fi
.
.IP "" 0
.
.P
Find the nodes running a version of Ubuntu:
.
.IP "" 4
.
.nf
knife search node \'platform:ubuntu*\'
.
.fi
.
.IP "" 0
.
.P
Find all nodes running CentOS in the production environment:
.
.IP "" 4
.
.nf
knife search node \'chef_environment:production AND platform:centos\'
.
.fi
.
.IP "" 0
.
.SH "KNOWN BUGS"
.
.IP "\(bu" 4
Searches against the client index return no results in most cases\. (CHEF\-2477)
.
.IP "\(bu" 4
Searches using the fuzzy match operator (~) produce an error\. (CHEF\-2478)
.
.IP "" 0
.
.SH "SEE ALSO"
\fBknife\-ssh\fR(1) \fIhttp://wiki\.opscode\.com/display/chef/Attributes\fR Lucene Query Parser Syntax \fIhttp://lucene\.apache\.org/java/2_3_2/queryparsersyntax\.html\fR
.
.SH "AUTHOR"
Chef was written by Adam Jacob \fIadam@opscode\.com\fR with many contributions from the community\.
.
.SH "DOCUMENTATION"
This manual page was written by Joshua Timberman \fIjoshua@opscode\.com\fR\. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2\.0 License\.
.
.SH "CHEF"
Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR
|
