Merge pull request #14776 from github/sabrowning1/queries-panel-language-selector

Add content for the queries panel and language selector

Author: sabrowning1

docs/codeql/codeql-for-visual-studio-code/analyzing-your-projects.rst

@@ -42,14 +42,47 @@ Downloading a database from GitHub
 
 .. include:: ../reusables/download-github-database.rst
 
+.. _filtering-databases-and-queries-by-language:
+
+Filtering databases and queries by language
+-------------------------------------------
+
+Optionally, to see databases containing a specific language and queries written for that language, you can apply a language filter using the language selector.
+
+#. To see available language filters, in the sidebar, click the **Language** title bar.
+#. Hover over the language filter you would like to apply, then click **Select**.
+
+   .. image:: ../images/codeql-for-visual-studio-code/choose-language-filter.png
+      :width: 350
+      :alt: Screenshot of the language selector. The "Select" button for a language filter is outlined in dark orange.
+
+Creating a custom query
+------------------------
+
+You can generate a query template for a specific language from the queries panel, then write your own code to quickly create a custom query.
+
+#. Optionally, to create a custom query in an existing directory, in the sidebar, click the **Queries** title bar to expand the queries panel, then select the desired directory.
+#. In the sidebar, hover over the **Queries** title bar, then click the **Create query** icon.
+
+   .. image:: ../images/codeql-for-visual-studio-code/create-query-icon.png
+      :width: 350
+      :alt: Screenshot of the queries panel. The "Create query" icon is outlined in dark orange.
+
+#. In the Command Palette, select the target language for your query. If you've chosen not to create your custom query in an existing directory, selecting a language will autogenerate a directory labeled ``codeql-custom-queries-<language>``, where ``<language>`` is the name of the selected language. A query template labeled ``example.ql`` will then be added to the existing or autogenerated directory.
+#. In the template, write your custom query, then save the file. Once your query is finished, you can run it from the queries panel.
+
 Running a query
 ------------------------
 
 The `CodeQL repository <https://github.com/github/codeql>`__ on GitHub contains lots of example queries.
-If you have that folder (or a different CodeQL pack) available in your workspace, you can access existing queries under ``<language>/ql/src/<category>``, for example ``java/ql/src/Likely Bugs``.
+You can access any existing queries in your workspace through the queries panel.
+
+#. In the sidebar, to expand the queries panel, click the **Queries** title bar.
+#. To run a query against the selected database, hover over the desired query, then click the **Run local query** icon.
 
-#. Open a query (``.ql``) file. It is displayed in the editor, with IntelliSense features such as syntax highlighting and autocomplete suggestions.
-#. Right-click in the query window and select **CodeQL: Run Query on Selected Database**. (Alternatively, run the command from the Command Palette.)
+   .. image:: ../images/codeql-for-visual-studio-code/run-local-query-icon.png
+      :width: 350
+      :alt: Screenshot of the mouse pointer hovering over a query in the queries panel. The "Run local query" icon is outlined in dark orange.
 
 The CodeQL extension runs the query on the current database and reports progress in the bottom right corner of the application.
 When the results are ready, they're displayed in the Results view.
@@ -61,6 +94,23 @@ For more information, see ":doc:`Troubleshooting CodeQL for Visual Studio Code <
 Running multiple queries
 --------------------------
 
+You can quickly run multiple queries against the database you've selected using the queries panel or a single command.
+
+Running all queries in a directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can easily run every query in a directory using the queries panel.
+
+#. In the sidebar, to expand the queries panel, click the **Queries** title bar.
+#. Hover over the desired directory of queries, then click the **Run local queries** icon.
+
+   .. image:: ../images/codeql-for-visual-studio-code/run-local-queries-icon.png
+      :width: 350
+      :alt: Screenshot of the mouse pointer hovering over a directory of queries in the queries panel. The "Run local queries" icon is outlined in dark orange.
+
+Running a selection of queries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 You can run multiple queries with a single command.
 
 #. Go to the File Explorer.
@@ -122,6 +172,7 @@ To see the queries that you have run in the current session, open the Query Hist
 
 The Query History contains information including the date and time when the query was run, the name of the query, the database on which it was run, and how long it took to run the query.
 To customize the information that is displayed, right-click an entry and select **Rename**.
+You can also filter the Query History view by language using the language selector. For more information, see ":ref:`Filtering databases and queries by language <filtering-databases-and-queries-by-language>`."
 
 Click an entry to display the corresponding results in the Query Results view, and double-click
 to display the query itself in the editor (or right-click and select **View Query**).