From 6eb1e1b24d3cdf888590c4142ca94aa46954b9e0 Mon Sep 17 00:00:00 2001 From: Jack Westwood Date: Wed, 11 Sep 2024 11:38:45 +0100 Subject: [PATCH] Reformat query docs --- docs/commands.adoc | 193 +-------------------------------------- docs/commands/query.adoc | 156 +++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+), 192 deletions(-) create mode 100644 docs/commands/query.adoc diff --git a/docs/commands.adoc b/docs/commands.adoc index 6e5dc98c..9f750ec9 100644 --- a/docs/commands.adoc +++ b/docs/commands.adoc @@ -356,198 +356,7 @@ The path parameter can be a list, allowing retrieval of multiple fields in one o ╰───┴────────────────┴───────────────────────────────────────────┴─────────────────────┴───────┴─────────╯ ``` -=== `query` commands - -``` -> query --help -Performs a n1ql query - -Usage: - > query {flags} - -Subcommands: - query advise - Calls the query adviser and lists recommended indexes - query indexes - Lists all query indexes - query transactions - Performs a n1ql query as a part of a transaction - -Flags: - -h, --help - Display the help message for this command - --clusters - the clusters to query against - --bucket - the bucket to query against - --scope - the scope to query against - --params - named or positional parameters for the query - --with-meta - include toplevel metadata - --disable-context - disable automatically detecting the query context based on the active bucket and scope - -Parameters: - statement : the query statement -``` - -The query commands can be used to explore/create indexes and execute queries. - -==== `query` - -The plain `query` command takes a n1ql statement and executes it against the active cluster. For example the following -gets the IDs of the landmark docs where the country is France: - -``` -👤 Administrator 🏠 cluster in 🗄 travel-sample._default._default -> query "SELECT meta().id FROM `travel-sample`.inventory.landmark WHERE country = 'France'" -╭─────┬────────────────┬─────────╮ -│ # │ id │ cluster │ -├─────┼────────────────┼─────────┤ -│ 0 │ landmark_10061 │ local │ -│ ... │ ... │ ... │ -│ 387 │ landmark_9838 │ local │ -╰─────┴────────────────┴─────────╯ -``` - -Named query parameters can be used by passing them in with the `--params` flag: - -``` -👤 Administrator 🏠 cluster in 🗄 travel-sample._default._default -> query "SELECT meta().id FROM `travel-sample`.inventory.landmark WHERE country = $country" --params {country: France} -╭─────┬────────────────┬─────────╮ -│ # │ id │ cluster │ -├─────┼────────────────┼─────────┤ -│ 0 │ landmark_10061 │ local │ -│ ... │ ... │ ... │ -│ 387 │ landmark_9838 │ local │ -╰─────┴────────────────┴─────────╯ -``` - -Multiple named parameters can be used at once, note there is no need to seperate them with commas: - -``` -👤 Administrator 🏠 cluster in 🗄 travel-sample._default._default -> query "SELECT airline FROM `travel-sample`.inventory.route WHERE sourceairport = $aval AND distance > $dval" --params {aval: LAX dval: 13000} -╭───┬─────────┬─────────╮ -│ # │ airline │ cluster │ -├───┼─────────┼─────────┤ -│ 0 │ B6 │ local │ -│ 1 │ EK │ local │ -│ 2 │ SV │ local │ -╰───┴─────────┴─────────╯ -``` - -The wildcard character '%' can be used the same as inside of the query statement. The following finds any IDs -that match the regex 'hotel1002*'. - -``` -👤 Administrator 🏠 cluster in 🗄 travel-sample._default._default -> query "SELECT meta().id FROM `travel-sample`.inventory.hotel WHERE meta().id LIKE $pattern" --params {pattern: hotel_1002%} -╭───┬─────────────┬─────────╮ -│ # │ id │ cluster │ -├───┼─────────────┼─────────┤ -│ 0 │ hotel_10025 │ local │ -│ 1 │ hotel_10026 │ local │ -╰───┴─────────────┴─────────╯ -``` - -==== `query advise` - -``` -> query advise --help -Calls the query adviser and lists recommended indexes - -Usage: - > query advise {flags} - -Flags: - -h, --help - Display the help message for this command - --with-meta - Includes related metadata in the result - --disable-context - disable automatically detecting the query context based on the active bucket and scope - --clusters - the clusters to query against - -Parameters: - statement : the query statement -``` - -The query advise command can help you to learn about the indexes that your queries are using, and what indexes -you could create to make them faster. For example we can take the first query from the `query` examples: - -[options="nowrap"] -``` -> query advise "SELECT meta().id FROM `travel-sample`.inventory.landmark WHERE country = 'France'" -╭───┬───────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────╮ -│ # │ #operator │ advice │ ... │ -├───┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────┤ -│ 0 │ Advise │ ╭────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ... │ -│ │ │ │ #operator │ IndexAdvice │ │ │ -│ │ │ │ │ ╭─────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ -│ │ │ │ adviseinfo │ │ │ ╭───┬─────────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────────╮ │ │ │ │ -│ │ │ │ │ │ current_indexes │ │ # │ index_statement │ keyspace_alias │ │ │ │ │ -│ │ │ │ │ │ │ ├───┼─────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────┤ │ │ │ │ -│ │ │ │ │ │ │ │ 0 │ CREATE PRIMARY INDEX def_inventory_landmark_primary ON `default`:`travel-sample`.`inventory`.`landmark` │ landmark │ │ │ │ │ -│ │ │ │ │ │ │ ╰───┴─────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────╯ │ │ │ │ -│ │ │ │ │ │ │ ╭──────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ │ -│ │ │ │ │ │ recommended_indexes │ │ │ ╭───┬─────────────────────────────────────────────────────────────────────────────────────────┬────────────────╮ │ │ │ │ │ -│ │ │ │ │ │ │ │ covering_indexes │ │ # │ index_statement │ keyspace_alias │ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ ├───┼─────────────────────────────────────────────────────────────────────────────────────────┼────────────────┤ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ │ 0 │ CREATE INDEX adv_country ON `default`:`travel-sample`.`inventory`.`landmark`(`country`) │ landmark │ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ ╰───┴─────────────────────────────────────────────────────────────────────────────────────────┴────────────────╯ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ ╭───┬─────────────────────────────────────────────────────────────────────────────────────────┬────────────────┬────────────────────────────────────────╮ │ │ │ │ │ -│ │ │ │ │ │ │ │ indexes │ │ # │ index_statement │ keyspace_alias │ recommending_rule │ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ ├───┼─────────────────────────────────────────────────────────────────────────────────────────┼────────────────┼────────────────────────────────────────┤ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ │ 0 │ CREATE INDEX adv_country ON `default`:`travel-sample`.`inventory`.`landmark`(`country`) │ landmark │ Index keys follow order of predicate │ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ │ │ │ │ types: 2. equality/null/missing. │ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ ╰───┴─────────────────────────────────────────────────────────────────────────────────────────┴────────────────┴────────────────────────────────────────╯ │ │ │ │ │ -│ │ │ │ │ │ │ ╰──────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │ │ │ │ -│ │ │ │ │ ╰─────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │ │ │ -│ │ │ ╰────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │ │ -╰───┴───────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────╯ -``` - -Here we can see that currently our statement uses the Primary index `def_inventory_landmark_primary` but it also -recommends a covering index that we can create. We can use the `query` command to create the new suggested index as follows: - -``` -query "CREATE INDEX adv_country ON `default`:`travel-sample`.`inventory`.`landmark`(`country`)" -``` - -==== `query indexes` -``` -> query indexes --help -Lists all query indexes - -Usage: - > query indexes {flags} - -Flags: - -h, --help - Display the help message for this command - --definitions - Whether to fetch the index definitions (changes the output format) - --clusters - the clusters to query against - --with-meta - Includes related metadata in the result - --disable-context - disable automatically detecting the query context based on the active bucket and scope -``` - -`query indexes` is very useful for managing and exploring indexes. If we had just created the recommended index at the -end of the `query advise` section, the nushell command `find` can be used in conjunction with `query indexes` to check -it was successfully created. - -[options="nowrap"] -``` -> query indexes | find adv_country -╭───┬───────────────┬───────────┬───────────────────┬──────────┬─────────────┬─────────┬───────────┬────────┬──────┬─────────╮ -│ # │ bucket │ condition │ index_key │ keyspace │ name │ primary │ scope │ state │ type │ cluster │ -├───┼───────────────┼───────────┼───────────────────┼──────────┼─────────────┼─────────┼───────────┼────────┼──────┼─────────┤ -│ 0 │ travel-sample │ │ ╭───┬───────────╮ │ landmark │ adv_country │ false │ inventory │ online │ gsi │ local │ -│ │ │ │ │ 0 │ `country` │ │ │ │ │ │ │ │ │ -│ │ │ │ ╰───┴───────────╯ │ │ │ │ │ │ │ │ -╰───┴───────────────┴───────────┴───────────────────┴──────────┴─────────────┴─────────┴───────────┴────────┴──────┴─────────╯ -``` - -And if we want to check the definition this can be done using the `--definitions` flag: - -[options="nowrap"] -``` -> query indexes --definitions | find adv_country -╭───┬───────────────┬───────────┬────────────┬─────────────┬────────┬──────────────┬──────────┬─────────────────────────────────────────────────────────────────────────────────┬─────────╮ -│ # │ bucket │ scope │ collection │ name │ status │ storage_mode │ replicas │ definition │ cluster │ -├───┼───────────────┼───────────┼────────────┼─────────────┼────────┼──────────────┼──────────┼─────────────────────────────────────────────────────────────────────────────────┼─────────┤ -│ 0 │ travel-sample │ inventory │ landmark │ adv_country │ Ready │ plasma │ 0 │ CREATE INDEX `adv_country` ON `travel-sample`.`inventory`.`landmark`(`country`) │ local │ -╰───┴───────────────┴───────────┴────────────┴─────────────┴────────┴──────────────┴──────────┴─────────────────────────────────────────────────────────────────────────────────┴─────────╯ -``` +include::commands/query.adoc[] === `vector` commands diff --git a/docs/commands/query.adoc b/docs/commands/query.adoc new file mode 100644 index 00000000..1d693cde --- /dev/null +++ b/docs/commands/query.adoc @@ -0,0 +1,156 @@ + +=== query + +The query commands can be used to explore/create indexes and execute queries. + +==== `query` + +Takes a n1ql statement and executes it against the active cluster. + +``` +👤 Charlie 🏠 local in 🗄 travel-sample._default._default +> query "SELECT meta().id FROM `travel-sample`.inventory.landmark WHERE country = 'France'" +╭─────┬────────────────┬─────────╮ +│ # │ id │ cluster │ +├─────┼────────────────┼─────────┤ +│ 0 │ landmark_10061 │ local │ +│ ... │ ... │ ... │ +│ 387 │ landmark_9838 │ local │ +╰─────┴────────────────┴─────────╯ +``` + +The query gets all the IDs of the docs where the country is France, then `cbsh` appends the cluster column to the results. + +Named parameters are supported through the `--params` flag when the argument is a json object: + +[options="nowrap"] +``` +👤 Charlie 🏠 local in 🗄 travel-sample._default._default +> query "SELECT meta().id FROM `travel-sample`.inventory.landmark WHERE country = $country" --params {country: France} +╭─────┬────────────────┬─────────╮ +│ # │ id │ cluster │ +├─────┼────────────────┼─────────┤ +│ 0 │ landmark_10061 │ local │ +│ ... │ ... │ ... │ +│ 387 │ landmark_9838 │ local │ +╰─────┴────────────────┴─────────╯ +``` + +Multiple named parameters can be used at once, note there is no need to separate them with commas: + +[options="nowrap"] +``` +👤 Charlie 🏠 local in 🗄 travel-sample._default._default +> query "SELECT airline FROM `travel-sample`.inventory.route WHERE sourceairport = $aval AND distance > $dval" --params {aval: LAX dval: 13000} +╭───┬─────────┬─────────╮ +│ # │ airline │ cluster │ +├───┼─────────┼─────────┤ +│ 0 │ B6 │ local │ +│ 1 │ EK │ local │ +│ 2 │ SV │ local │ +╰───┴─────────┴─────────╯ +``` + +The wildcard character '%' can be used the same as inside of the query statement. +The following finds any IDs that match the regex 'hotel1002*'. + +[options="nowrap"] +``` +👤 Charlie 🏠 local in 🗄 travel-sample._default._default +> query "SELECT meta().id FROM `travel-sample`.inventory.hotel WHERE meta().id LIKE $pattern" --params {pattern: hotel_1002%} +╭───┬─────────────┬─────────╮ +│ # │ id │ cluster │ +├───┼─────────────┼─────────┤ +│ 0 │ hotel_10025 │ local │ +│ 1 │ hotel_10026 │ local │ +╰───┴─────────────┴─────────╯ +``` + +Positional parameters are also supported when the `--params` flag takes a https://www.nushell.sh/book/working_with_lists.html[list] argument: + +[options="nowrap"] +``` +👤 Charlie 🏠 local +> query "SELECT airline FROM `travel-sample`.inventory.route WHERE sourceairport = $1 AND distance > $2" --params [LAX 13000] +╭───┬─────────┬─────────╮ +│ # │ airline │ cluster │ +├───┼─────────┼─────────┤ +│ 0 │ B6 │ local │ +│ 1 │ EK │ local │ +│ 2 │ SV │ local │ +╰───┴─────────┴─────────╯ +``` + +==== `query advise` + +Helps you to learn about the indexes that your queries are using, and what indexes +you could create to make them faster. For example we can take the first query from the `query` examples: + +[options="nowrap"] +``` +> query advise "SELECT meta().id FROM `travel-sample`.inventory.landmark WHERE country = 'France'" +╭───┬───────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────╮ +│ # │ #operator │ advice │ ... │ +├───┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────┤ +│ 0 │ Advise │ ╭────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ... │ +│ │ │ │ #operator │ IndexAdvice │ │ │ +│ │ │ │ │ ╭─────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ +│ │ │ │ adviseinfo │ │ │ ╭───┬─────────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────────╮ │ │ │ │ +│ │ │ │ │ │ current_indexes │ │ # │ index_statement │ keyspace_alias │ │ │ │ │ +│ │ │ │ │ │ │ ├───┼─────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────┤ │ │ │ │ +│ │ │ │ │ │ │ │ 0 │ CREATE PRIMARY INDEX def_inventory_landmark_primary ON `default`:`travel-sample`.`inventory`.`landmark` │ landmark │ │ │ │ │ +│ │ │ │ │ │ │ ╰───┴─────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────╯ │ │ │ │ +│ │ │ │ │ │ │ ╭──────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ │ +│ │ │ │ │ │ recommended_indexes │ │ │ ╭───┬─────────────────────────────────────────────────────────────────────────────────────────┬────────────────╮ │ │ │ │ │ +│ │ │ │ │ │ │ │ covering_indexes │ │ # │ index_statement │ keyspace_alias │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ ├───┼─────────────────────────────────────────────────────────────────────────────────────────┼────────────────┤ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ 0 │ CREATE INDEX adv_country ON `default`:`travel-sample`.`inventory`.`landmark`(`country`) │ landmark │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ ╰───┴─────────────────────────────────────────────────────────────────────────────────────────┴────────────────╯ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ ╭───┬─────────────────────────────────────────────────────────────────────────────────────────┬────────────────┬────────────────────────────────────────╮ │ │ │ │ │ +│ │ │ │ │ │ │ │ indexes │ │ # │ index_statement │ keyspace_alias │ recommending_rule │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ ├───┼─────────────────────────────────────────────────────────────────────────────────────────┼────────────────┼────────────────────────────────────────┤ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ 0 │ CREATE INDEX adv_country ON `default`:`travel-sample`.`inventory`.`landmark`(`country`) │ landmark │ Index keys follow order of predicate │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ types: 2. equality/null/missing. │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ ╰───┴─────────────────────────────────────────────────────────────────────────────────────────┴────────────────┴────────────────────────────────────────╯ │ │ │ │ │ +│ │ │ │ │ │ │ ╰──────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │ │ │ │ +│ │ │ │ │ ╰─────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │ │ │ +│ │ │ ╰────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │ │ +╰───┴───────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────╯ +``` + +This shows our query statement uses the Primary index `def_inventory_landmark_primary` and also recommends a covering index that we can create using `query`: + +``` +> query "CREATE INDEX adv_country ON `default`:`travel-sample`.`inventory`.`landmark`(`country`)" +``` + +==== `query indexes` + +Lists all of the query indexes. +If we had just created the recommended index at the end of the `query advise` section, the nushell command `find` can be used in conjunction with `query indexes` to check it was successfully created. + +[options="nowrap"] +``` +> query indexes | find adv_country +╭───┬───────────────┬───────────┬───────────────────┬──────────┬─────────────┬─────────┬───────────┬────────┬──────┬─────────╮ +│ # │ bucket │ condition │ index_key │ keyspace │ name │ primary │ scope │ state │ type │ cluster │ +├───┼───────────────┼───────────┼───────────────────┼──────────┼─────────────┼─────────┼───────────┼────────┼──────┼─────────┤ +│ 0 │ travel-sample │ │ ╭───┬───────────╮ │ landmark │ adv_country │ false │ inventory │ online │ gsi │ local │ +│ │ │ │ │ 0 │ `country` │ │ │ │ │ │ │ │ │ +│ │ │ │ ╰───┴───────────╯ │ │ │ │ │ │ │ │ +╰───┴───────────────┴───────────┴───────────────────┴──────────┴─────────────┴─────────┴───────────┴────────┴──────┴─────────╯ +``` + +And if we want to check the definition this can be done using the `--definitions` flag: + +[options="nowrap"] +``` +> query indexes --definitions | find adv_country +╭───┬───────────────┬───────────┬────────────┬─────────────┬────────┬──────────────┬──────────┬─────────────────────────────────────────────────────────────────────────────────┬─────────╮ +│ # │ bucket │ scope │ collection │ name │ status │ storage_mode │ replicas │ definition │ cluster │ +├───┼───────────────┼───────────┼────────────┼─────────────┼────────┼──────────────┼──────────┼─────────────────────────────────────────────────────────────────────────────────┼─────────┤ +│ 0 │ travel-sample │ inventory │ landmark │ adv_country │ Ready │ plasma │ 0 │ CREATE INDEX `adv_country` ON `travel-sample`.`inventory`.`landmark`(`country`) │ local │ +╰───┴───────────────┴───────────┴────────────┴─────────────┴────────┴──────────────┴──────────┴─────────────────────────────────────────────────────────────────────────────────┴─────────╯ +``` + +Check this https://couchbase.sh/docs/recipes.html#_migrating_query_index_definitions[snippet] to see how `query indexes` can be used to to migrate indexes between clusters. \ No newline at end of file