Merge pull request #10389 from github/aeisenberg/suites-docs

Tweak the query suites documentation

Author: aeisenberg

docs/codeql/codeql-cli/creating-codeql-query-suites.rst

@@ -118,8 +118,10 @@ typically a query metadata property. The value can be:
 
 To match a constraint, a metadata value must match one of the strings or
 regular expressions. When there is more than one metadata key, each key must be matched.
-For more information about query metadata properties, see ":ref:`Metadata for CodeQL queries
-<metadata-for-codeql-queries>`."
+The standard metadata keys available to match on are: ``description``, ``id``, ``kind``,
+``name``, ``tags``, ``precision``, and ``problem.severity``.
+For more information about query metadata properties, see
+":ref:`Metadata for CodeQL queries <metadata-for-codeql-queries>`."
 
 In addition to metadata tags, the keys in the constraint block can also be:
 
@@ -131,8 +133,37 @@ In addition to metadata tags, the keys in the constraint block can also be:
 - ``tags contain all``---each of the given match strings must match one of the
   components of the ``@tags`` metadata property.
 
-Examples
-~~~~~~~~
+Examples of filtering which queries are run
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A common use case is to create a query suite that runs all queries in a CodeQL pack,
+except for a few specific queries that the user does not want to run. In general, we
+recommend filtering on the query ``id``, which is a unique and stable identifier for
+each query. The following three query suite definitions are semantically identical and
+filter by the query ``id``:
+
+This filter matches all the queries in the default suite of ``codeql/cpp-queries``, except for the two queries with the excluded identifiers::
+
+   - qlpack: codeql/cpp-queries
+   - exclude:
+       id:
+         - cpp/cleartext-transmission
+         - cpp/cleartext-storage-file
+
+In this example, a separate ``exclude`` instruction is used for each query::
+
+   - qlpack: codeql/cpp-queries
+   - exclude:
+       id: cpp/cleartext-transmission
+   - exclude:
+       id: cpp/cleartext-storage-file
+
+In this example, a regular expression excludes the same two queries. It would also exclude any future queries added to the suite with identifiers that begin: ``cpp/cleartext-``::
+
+   - qlpack: codeql/cpp-queries
+   - exclude:
+       id:
+         - /^cpp\/cleartext-.*/
 
 To define a suite that selects all queries in the default suite of the
 ``codeql/cpp-queries`` CodeQL pack, and then refines them to only include
@@ -150,6 +181,15 @@ and ``@precision high`` from the ``my-custom-queries`` directory, use::
        kind: problem
        precision: very-high
 
+Note that the following query suite definition behaves differently from the definition above. This definition selects queries that are ``@kind problem`` *or*
+are ``@precision very-high``::
+
+   - queries: my-custom-queries
+   - include:
+       kind: problem
+   - include:
+       precision: very-high
+
 To create a suite that selects all queries with ``@kind problem`` from the
 ``my-custom-queries`` directory except those with ``@problem.severity
 recommendation``, use::
@@ -172,6 +212,15 @@ use::
        - high
        - very-high
 
+.. pull-quote::
+
+    Tip
+
+    You can use the ``codeql resolve queries /path/to/suite.qls`` command to see
+    which queries are selected by a query suite definition. For more information,
+    see the `resolve queries <../../codeql-cli/manual/resolve-queries>`__
+    reference documentation.
+
 Reusing existing query suite definitions
 -----------------------------------------
 
@@ -208,14 +257,8 @@ Existing query suite definitions can be reused by specifying:
   conditions, saved in a ``.yml`` file, to multiple query definitions. For more
   information, see the `example <#example>`__ below.
 
-- An ``eval`` instruction---performs the same function as an ``import``
-  instruction, but takes a full suite definition as the argument, rather than the
-  path to a ``.qls`` file on disk.
-
-To see what queries are included in a query suite, you can run the ``codeql resolve queries my-suite.qls`` command.
-
-Example
-~~~~~~~
+Reusability Examples
+~~~~~~~~~~~~~~~~~~~~
 
 To use the same conditions in multiple query suite definitions, create a
 separate ``.yml`` file containing your instructions. For example, save the
@@ -252,6 +295,30 @@ instruction::
     from: my-org/my-custom-instructions
     version: ^1.2.3 # optional
 
+A common use case for an ``import`` instruction is to apply a further filter to queries from another
+query suite. For example, this suite will further filter the ``cpp-security-and-quality`` suite
+and exclude ``low`` and ``medium`` precision queries::
+
+    - import: codeql-suites/cpp-security-and-quality.qls
+      from: codeql/cpp-queries
+    - exclude:
+        precision:
+          - low
+          - medium
+
+If you want to ``include`` queries imported from another suite, the syntax is a little different::
+
+    - import: codeql-suites/cpp-security-and-quality.qls
+      from: codeql/cpp-queries
+    - exclude: {}
+    - include:
+        precision:
+          - very-high
+          - high
+
+Notice the empty ``exclude`` instruction. This is required to ensure that the subsequent ``include``
+instruction is able to filter queries from the imported suite.
+
 Naming a query suite
 --------------------