Query help reference

This topic provides detailed information on the structure of query help files. For more information about how to write useful query help in a style that is consistent with the standard CodeQL queries, see the Query help style guide on GitHub.

Note

You can access the query help for CodeQL queries by visiting the Built-in query pages. You can also access the raw query help files in the GitHub repository. For example, see the JavaScript security queries and C/C++ critical queries.

For queries run by default on LGTM, there are several different ways to access the query help. For further information, see Where do I see the query help for a query on LGTM? in the LGTM user help.

Overview

Each query help file provides detailed information about the purpose and use of a query. When you write your own queries, we recommend that you also write query help files so that other users know what the queries do, and how they work.

Structure

Query help files are written using an XML format called Qhelp (.qhelp). Query help files must have the same base name as the query they describe, and must be located in the same directory. The basic structure is as follows:

<!DOCTYPE qhelp SYSTEM "qhelp.dtd">
<qhelp>
    CONTAINS one or more section-level elements
</qhelp>

The header and single top-level qhelp element are both mandatory. The following sections explain additional elements that you may include in your query help files.

Section-level elements

Section-level elements are used to group the information in the help file into sections. Many sections have a heading, either defined by a title attribute or a default value. The following section-level elements are optional child elements of the qhelp element.

Element Attributes Children Purpose of section
example None Any block element Demonstrate an example of code that violates the rule implemented by the query with guidance on how to fix it. Default heading.
fragment None Any block element See Qhelp inclusion below. No heading.
hr None None A horizontal rule. No heading.
include src The Qhelp file to include. None Include a Qhelp file at the location of this element. See Qhelp inclusion below. No heading.
overview None Any block element Overview of the purpose of the query. Typically this is the first section in a query document. No heading.
recommendation None Any block element Recommend how to address any alerts that this query identifies. Default heading.
references None li elements Reference list. Typically this is the last section in a query document. Default heading.
section title Title of the section Any block element General-purpose section with a heading defined by the title attribute.
semmleNotes None Any block element Semmle-specific notes about the query. This section is used only for queries that implement a rule defined by a third party. Default heading.

Block elements

The following elements are optional child elements of the section, example, fragmentrecommendation, overview and semmleNotes elements.

Element Attributes Children Purpose of block
blockquote None Any block element Display a quoted paragraph.
img
src The image file to include.
alt Text for the image’s alt text.
height Optional, height of the image.
width Optional, the width of the image.
None Display an image. The content of the image is in a separate image file.
include src The Qhelp file to include. None Include a Qhelp file at the location of this element. See Qhelp inclusion below for more information.
ol None li Display an ordered list. See List elements below.
p None Any inline content Display a paragraph, used as in HTML files.
pre None Text Display text in a monospaced font with preformatted whitespace.
sample
language The language of the in-line code sample.
src Optional, the file containing the sample code.
Text Display sample code either defined as nested text in the sample element or defined in the src file specified. When src is specified, the language is inferred from the file extension. If src is omitted, then language must be provided and the sample code provided as nested text.
table None tbody Display a table. See Tables below.
ul None li Display an unordered list. See List elements below.
warning None Text Display a warning that will be displayed very visibly on the resulting page. Such warnings are sometimes used on queries that are known to have low precision for many code bases; such queries are often disabled by default.

List elements

Qhelp files support two types of block elements for lists: ul and ol. Both block elements support only one child elements of the type li. Each li element contains either inline content or a block element.

Table elements

The table block element is used to include a table in a Qhelp file. Each table includes a number of rows, each of which includes a number of cells. The data in the cells will be rendered as a grid.

Element Attributes Children Purpose
tbody None tr Defines the top-level element of a table.
tr None
th
td
Defines one row of a table.
td None Any inline content Defines one cell of a table row.
th None Any inline content Defines one header cell of a table row.

Inline content

Inline content is used to define the content for paragraphs, list items, table cells, and similar elements. Inline content includes text in addition to the inline elements defined below:

Element Attributes Children Purpose
a href The URL of the link. text Defines hyperlink. When a user selects the child text, they will be redirected to the given URL.
b None Inline content Defines content that should be displayed as bold face.
code None Inline content Defines content representing code. It is typically shown in a monospace font.
em None Inline content Defines content that should be emphasized, typically by italicizing it.
i None Inline content Defines content that should be displayed as italics.
img
src
alt
height
width
None Display an image. See the description above in Block elements.
strong None Inline content Defines content that should be rendered more strongly, typically using bold face.
sub None Inline content Defines content that should be rendered as subscript.
sup None Inline content Defines content that should be rendered as superscript.
tt None Inline content Defines content that should be displayed with a monospace font.

Qhelp inclusion

To enable the reuse of content between different help topics, shared content can be stored in one Qhelp file and then included in a number of other Qhelp files using the include element. The shared content can stored either in the same directory as the including files, or in SEMMLE_DIST/docs/include.

The include element can be used as a section or block element, the content of the Qhelp file defined by the src attribute must contain elements that are appropriate to the location of the include element.

Section-level include elements

Section-level include elements can be located beneath the top-level qhelp element. For example, in StoredXSS.qhelp, a full query help file is reused:

<qhelp>
    <include src="XSS.qhelp" />
</qhelp>

In this example, the XSS.qhelp file must conform to the standard for a full Qhelp file as described above. That is, the qhelp element may only contain non-fragment, section-level elements.

Block-level include elements

Block-level include elements can be included beneath section-level elements. For example, an include element is used beneath the overview section in ThreadUnsafeICryptoTransform.qhelp:

<qhelp>
    <overview>
        <include src="ThreadUnsafeICryptoTransformOverview.qhelp" />
    </overview>
    ...
</qhelp>

The included file, ThreadUnsafeICryptoTransformOverview.qhelp, may only contain one or more fragment sections. For example:

<!DOCTYPE qhelp SYSTEM "qhelp.dtd">
<qhelp>
   <fragment>
      <p>
         ...
      </p>
   </fragment>
</qhelp>

Further information

  • To learn more about contributing to the standard CodeQL queries and libraries, see our Contributing guidelines on GitHub.
  • To learn more about writing custom queries, and how to format your code for clarity and consistency, see Writing CodeQL queries.