Initial Chef repository

cookbooks/partial_search/README.md

@@ -0,0 +1,82 @@
+Partial Search Cookbook
+=======================
+[Partial Search](http://docs.opscode.com/essentials_search.html#partial-search)
+is a search API available on Chef Server. (see Notes below for version compatibility)  
+It can be used to reduce the network bandwidth and the memory used by
+chef-client to process search results.
+
+This cookbook provides an experimental interface to the partial search
+API by providing a `partial_search` method that can be used instead of
+the `search` method in your recipes.
+
+Since Chef Client 11.10.0 the partial_search capability has been built-in
+so it does not require this cookbook.
+
+The `partial_search` method allows you to retrieve just the attributes
+of interest. For example, you can execute a search to return just the
+name and IP addresses of the nodes in your infrastructure rather than
+receiving an array of complete node objects and post-processing them.
+
+
+Install
+-------
+Upload this cookbook and include it in the dependencies of any
+cookbook where you would like to use `partial_search`.
+
+
+Usage
+-----
+When you call `partial_search`, you need to specify the key paths of the
+attributes you want returned. Key paths are specified as an array
+of strings. Each key path is mapped to a short name of your
+choosing. Consider the following example:
+
+```ruby
+partial_search(:node, 'role:web',
+   :keys => { 'name' => [ 'name' ],
+              'ip'   => [ 'ipaddress' ],
+              'kernel_version' => [ 'kernel', 'version' ]
+            }
+).each do |result|
+  puts result['name']
+  puts result['ip']
+  puts result['kernel_version']
+end
+```
+
+In the example above, two attributes will be extracted (on the
+server) from the nodes that match the search query. The result will
+be a simple hash with keys 'name'  and 'ip'.
+
+
+Notes
+-----
+* We would like your feedback on this feature and the interface
+  provided by this cookbook. Please send comments to the chef-dev
+  mailing list.
+
+* The partial search API is available in the Open Source Chef Server since 11.0.4
+
+* The partial search API is available in Enterprise Chef Server since 1.2.2
+
+
+License & Authors
+-----------------
+- Author:: Adam Jacob (<adam@opscode.com>)
+- Author:: John Keiser (<jkeiser@opscode.com>)
+
+```text
+Copyright:: 2012-2013, Opscode, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```