From fb0057662b80a15c0a6e05d2a4a6a8b5962a2415 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yannig=20Perr=C3=A9?= Date: Fri, 28 Oct 2016 23:32:53 +0200 Subject: [PATCH 1/2] json_query documentation. --- docsite/rst/playbooks_filters.rst | 65 +++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/docsite/rst/playbooks_filters.rst b/docsite/rst/playbooks_filters.rst index 562fb385a8..d698b96b5d 100644 --- a/docsite/rst/playbooks_filters.rst +++ b/docsite/rst/playbooks_filters.rst @@ -211,6 +211,71 @@ Square root, or the 5th:: Note that jinja2 already provides some like abs() and round(). +.. _query_filter: + +Query json filter +----------------- + +Sometimes you end up with complex data structure in json format and you need to extract only a small set of data within it. **json_query** filter let you query a complexe json structure in order to iterate over it using a with_items for example. + +.. note:: This filter is build upon **jmespath**. You can use the same syntax and have a look at this `jmespath examples `_. + +Now, let's take the following data structure:: + + domain_definition: + domain: + cluster: + - name: "cluster1" + - name: "cluster2" + server: + - name: "server11" + cluster: "cluster1" + port: "8080" + - name: "server12" + cluster: "cluster1" + port: "8090" + - name: "server21" + cluster: "cluster2" + port: "9080" + - name: "server22" + cluster: "cluster2" + port: "9090" + library: + - name: "lib1" + target: "cluster1" + - name: "lib2" + target: "cluster2" + +You wan't to extract all clusters from this structure. you can do this using the following query:: + + - name: "Display all clusters name" + debug: var=item + with_items: "{{domain_definition|json_query('domain.cluster[*].name')}}" + +Same things for all server's name:: + + - name: "Display all servers name" + debug: var=item + with_items: "{{domain_definition|json_query('domain.server[*].name')}}" + +Another little example where we only show ports from cluster1:: + + - name: "Display all servers name from cluster1" + debug: var=item + with_items: "{{domain_definition|json_query(server_name_cluster1_query)}}" + vars: + server_name_cluster1_query: "domain.server[?cluster=='cluster1'].port" + +.. note:: We must use a variable in order to use quote in our query. + +And a last example where we get a hash map with port and name of cluster's members:: + + - name: "Display all servers port and name from cluster1" + debug: var=item + with_items: "{{domain_definition|json_query(server_name_cluster1_query)}}" + vars: + server_name_cluster1_query: "domain.server[?cluster=='cluster2'].{name: name, port: port}" + .. _ipaddr_filter: IP address filter From 8e27dc49a7e7b81e233a01d37255e5d06b51ffcf Mon Sep 17 00:00:00 2001 From: scottb Date: Tue, 8 Nov 2016 13:45:56 -0800 Subject: [PATCH 2/2] Update playbooks_filters.rst Edited for grammar, spelling, mechanical. --- docsite/rst/playbooks_filters.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docsite/rst/playbooks_filters.rst b/docsite/rst/playbooks_filters.rst index d698b96b5d..0c3e5ecbdf 100644 --- a/docsite/rst/playbooks_filters.rst +++ b/docsite/rst/playbooks_filters.rst @@ -211,14 +211,14 @@ Square root, or the 5th:: Note that jinja2 already provides some like abs() and round(). -.. _query_filter: +.. json_query_filter: -Query json filter +JSON Query Filter ----------------- -Sometimes you end up with complex data structure in json format and you need to extract only a small set of data within it. **json_query** filter let you query a complexe json structure in order to iterate over it using a with_items for example. +Sometimes you end up with complex data structure in JSON format and you need to extract only a small set of data within it. A **json_query** filter lets you query a complex JSON structure and iterate over it using a with_items structure. -.. note:: This filter is build upon **jmespath**. You can use the same syntax and have a look at this `jmespath examples `_. +.. note:: This filter is built upon **jmespath**, and you can use the same syntax. For examples, see `jmespath examples `_. Now, let's take the following data structure:: @@ -246,31 +246,31 @@ Now, let's take the following data structure:: - name: "lib2" target: "cluster2" -You wan't to extract all clusters from this structure. you can do this using the following query:: +To extract all clusters from this structure, you can use the following query:: - - name: "Display all clusters name" + - name: "Display all cluster names" debug: var=item with_items: "{{domain_definition|json_query('domain.cluster[*].name')}}" -Same things for all server's name:: +Same things for all server names:: - - name: "Display all servers name" + - name: "Display all server names" debug: var=item with_items: "{{domain_definition|json_query('domain.server[*].name')}}" -Another little example where we only show ports from cluster1:: +This example shows ports from cluster1:: - - name: "Display all servers name from cluster1" + - name: "Display all server names from cluster1" debug: var=item with_items: "{{domain_definition|json_query(server_name_cluster1_query)}}" vars: server_name_cluster1_query: "domain.server[?cluster=='cluster1'].port" -.. note:: We must use a variable in order to use quote in our query. +.. note:: You must use a variable in order to use quotes in your query. -And a last example where we get a hash map with port and name of cluster's members:: +In this example, we get a hash map with all ports and names of a cluster:: - - name: "Display all servers port and name from cluster1" + - name: "Display all server ports and names from cluster1" debug: var=item with_items: "{{domain_definition|json_query(server_name_cluster1_query)}}" vars: