You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/codeql/writing-codeql-queries/defining-the-results-of-a-query.rst
+34-42Lines changed: 34 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,8 +9,8 @@ About query results
9
9
-------------------
10
10
11
11
The information contained in the results of a query is controlled by the ``select`` statement. Part of the process of developing a useful query is to make the results clear and easy for other users to understand.
12
-
When you write your own queries in the query console or in the CodeQL :ref:`extension for VS Code <codeql-for-visual-studio-code>` there are no constraints on what can be selected.
13
-
However, if you want to use a query to create alerts in LGTM or generate valid analysis results using the :ref:`CodeQL CLI <codeql-cli>`, you'll need to make the ``select`` statement report results in the required format.
12
+
When you write your own queries in the CodeQL :ref:`extension for VS Code <codeql-for-visual-studio-code>` there are no constraints on what can be selected.
13
+
However, if you want to use a query to create alerts for code scanning or generate valid analysis results using the :ref:`CodeQL CLI <codeql-cli>`, you'll need to make the ``select`` statement report results in the required format.
14
14
You must also ensure that the query has the appropriate metadata properties defined.
15
15
This topic explains how to write your select statement to generate helpful analysis results.
16
16
@@ -23,7 +23,7 @@ In their most basic form, the ``select`` statement must select two 'columns':
23
23
- **Element**—a code element that's identified by the query. This defines the location of the alert.
24
24
- **String**—a message to display for this code element, describing why the alert was generated.
25
25
26
-
If you look at some of the LGTM queries, you'll see that they can select extra element/string pairs, which are combined with ``$@`` placeholder markers in the message to form links. For example, `Dereferenced variable may be null <https://lgtm.com/query/rule:1954750296/lang:java/>`__ (Java), or `Duplicate switch case <https://lgtm.com/query/rule:7890077/lang:javascript/>`__ (JavaScript).
26
+
If you look at some of the existing queries, you'll see that they can select extra element/string pairs, which are combined with ``$@`` placeholder markers in the message to form links. For example, `Dereferenced variable may be null <https://github.com/github/codeql/blob/95e65347cafe502bbd0d9f48d1175fd3d66e0459/java/ql/src/Likely%20Bugs/Nullness/NullMaybe.ql>`__ (Java), or `Duplicate switch case <https://github.com/github/codeql/blob/95e65347cafe502bbd0d9f48d1175fd3d66e0459/javascript/ql/src/Expressions/DuplicateSwitchCase.ql>`__ (JavaScript).
27
27
28
28
.. pull-quote::
29
29
@@ -34,78 +34,70 @@ If you look at some of the LGTM queries, you'll see that they can select extra e
34
34
Developing a select statement
35
35
-----------------------------
36
36
37
-
Here's a simple query that uses the standard CodeQL ``CodeDuplication.qll`` library to identify similar files.
37
+
Here's a simple query to find Java classes that extend other classes.
38
38
39
39
Basic select statement
40
40
~~~~~~~~~~~~~~~~~~~~~~
41
41
42
42
.. code-block:: ql
43
43
44
-
import java
45
-
import external.CodeDuplication
46
-
47
-
from File f, File other, int percent
48
-
where similarFiles(f, other, percent)
49
-
select f, "This file is similar to another file."
44
+
/**
45
+
* @kind problem
46
+
*/
47
+
48
+
import java
49
+
50
+
from Class c, Class superclass
51
+
where superclass = c.getASupertype()
52
+
select c, "This class extends another class."
50
53
51
54
This basic select statement has two columns:
52
55
53
-
#. Element to display the alert on: ``f`` corresponds to ``File``.
54
-
#. String message to display: ``"This file is similar to another file."``
56
+
#. An element with a location to display the alert on: ``c`` corresponds to ``Class``.
57
+
#. String message to display: ``"This class extends another class."``
The alert message defined by the basic select statement is constant and doesn't give users much information. Since the query identifies the similar file (``other``), it's easy to extend the ``select`` statement to report the name of the similar file. For example:
66
+
The alert message defined by the basic select statement is constant and doesn't give users much information. Since the query identifies the superclass, it's easy to include its name in the string message. For example:
64
67
65
68
.. code-block:: ql
66
69
67
-
select f, "This file is similar to " + other.getBaseName()
70
+
select c, "This class extends the class " + superclass.getName()
68
71
69
-
#. Element: ``f`` as before.
70
-
#. String message: ``"This file is similar to "``—the string text is combined with the file name for the ``other``, similar file, returned by ``getBaseName()``.
72
+
#. Element: ``c`` as before.
73
+
#. String message: ``"This class extends the class "``—the string text is combined with the class name for the ``superclass``, returned by ``getName()``.
While this is more informative than the original select statement, the user still needs to find the other file manually.
79
+
While this is more informative than the original select statement, the user still needs to find the superclass manually.
77
80
78
-
Adding a link to the similar file
79
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81
+
Adding a link to the superclass
82
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
83
81
-
You can use placeholders in the text of alert messages to insert additional information, such as links to the similar file. Placeholders are defined using ``$@``, and filled using the information in the next two columns of the select statement. For example, this select statement returns four columns:
84
+
You can use placeholders in the text of alert messages to insert additional information, such as links to the superclass. Placeholders are defined using ``$@``, and filled using the information in the next two columns of the select statement. For example, this select statement returns four columns:
82
85
83
86
.. code-block:: ql
84
87
85
-
select f, "This file is similar to $@.", other, other.getBaseName()
88
+
select c, "This class extends the class $@.", superclass, superclass.getName()
86
89
87
-
#. Element: ``f`` as before.
88
-
#. String message: ``"This file is similar to $@."``—the string text now includes a placeholder, which will display the combined content of the next two columns.
89
-
#. Element for placeholder: ``other`` corresponds to the similar file.
90
-
#. String text for placeholder: the short file name returned by ``other.getBaseName()``.
90
+
#. Element: ``c`` as before.
91
+
#. String message: ``"This class extends the class $@."``—the string text now includes a placeholder, which will display the combined content of the next two columns.
92
+
#. Element for placeholder: the ``superclass``.
93
+
#. String text for placeholder: the class name returned by ``superclass.getBaseName()``.
91
94
92
-
When the alert message is displayed, the ``$@`` placeholder is replaced by a link created from the contents of the third and fourth columns defined by the ``select`` statement.
95
+
When the alert message is displayed, the ``$@`` placeholder is replaced by a link created from the contents of the third and fourth columns defined by the ``select`` statement. In this example, the link target will be the location of the superclass's definition, and the link text will be its name. Note that some superclasses, such as ``Object``, will not be in the database, since they are built in to the Java language. Clicking those links will have no effect.
93
96
94
97
If you use the ``$@`` placeholder marker multiple times in the description text, then the ``N``\ th use is replaced by a link formed from columns ``2N+2`` and ``2N+3``. If there are more pairs of additional columns than there are placeholder markers, then the trailing columns are ignored. Conversely, if there are fewer pairs of additional columns than there are placeholder markers, then the trailing markers are treated as normal text rather than placeholder markers.
95
98
96
-
Adding details of the extent of similarity
97
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98
-
99
-
You could go further and change the ``select`` statement to report on the similarity of content in the two files, since this information is already available in the query. For example:
100
-
101
-
.. code-block:: ql
102
-
103
-
select f, percent + "% of the lines in " + f.getBaseName() + " are similar to lines in $@.", other, other.getBaseName()
104
-
105
-
The new elements added here don't need to be clickable, so we added them directly to the description string.
0 commit comments