• CodeQL »
• Writing CodeQL queries »
• CodeQL queries »

Query help files

Query help files tell users the purpose of a query, and recommend how to solve the potential problem the query finds.

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 CodeQL query help. You can also access the raw query help files in the GitHub repository. For example, see the JavaScript/TypeScript security queries and C/C++ critical queries.

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 a custom XML format, and stored in a file with a .qhelp extension. 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.

Code scanning does not process .qhelp files for custom CodeQL queries, so to show query help for custom queries in the code scanning UI you must convert the .qhelp files to markdown and then include the markdown-rendered query help in SARIF files generated during an analysis. For more information, see “Analyzing databases with the CodeQL CLI.”

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 “Query help inclusion” below. No heading.
hr	None	None	A horizontal rule. No heading.
include	src The query help file to include.	None	Include a query help file at the location of this element. See “Query help 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	Implementation 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, fragment, recommendation, 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 query help file to include.	None	Include a query help file at the location of this element. See Query help 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

Query help 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 query help 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.

Query help inclusion

To reuse content between different help topics, you can store shared content in one query help file and then include it in a number of other query help files using the include element. The shared content can be stored either in the same directory as the including files, or in SEMMLE_DIST/docs/include. When a query help file is only included by other help files but does not belong to a specific query, it should have the file extension .inc.qhelp.

The include element can be used as a section or block element. The content of the query help 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 query help 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.inc.qhelp" />
    </overview>
    ...
</qhelp>

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

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

• © GitHub, Inc.
• Terms
• Privacy