hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-05-01 11:45:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

update ql-language-reference links

Browse Source
This commit is contained in:
james
2020-11-05 14:54:14 +00:00
parent e5fff6445a
commit f85f99c6c2
15 changed files with 42 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/language/README.rst
View File

@@ -18,7 +18,7 @@ Project structure
The documentation currently consists of the following Sphinx projects:
- ``learn-ql``–help topics to help you learn CodeQL and write queries
- ``ql-handbook``–an overview of important concepts in QL, the language that underlies CodeQL analysis
- ``ql-language-reference``–an overview of important concepts in QL, the language that underlies CodeQL analysis
- ``support``–the languages and frameworks currently supported in CodeQL analysis
- ``ql-training``–source files for the CodeQL training and variant analysis examples slide decks

4
docs/language/learn-ql/about-data-flow-analysis.rst
View File

@@ -49,8 +49,8 @@ flow between functions and through object properties. Global data flow, however,
graph that do not precisely correspond to the flow of values, but model whether some value at runtime may be derived from another, for instance through a string manipulating
operation.
The data flow graph is computed using `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ to model the program elements that represent the graph's nodes.
The flow of data between the nodes is modeled using `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to compute the graph's edges.
The data flow graph is computed using `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ to model the program elements that represent the graph's nodes.
The flow of data between the nodes is modeled using `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ to compute the graph's edges.
Computing an accurate and complete data flow graph presents several challenges:

4
docs/language/learn-ql/beginner/catch-the-fire-starter.rst
View File

@@ -14,7 +14,7 @@ Read the examples below to learn how to define predicates and classes in QL. The
Select the southerners
----------------------
This time you only need to consider a specific group of villagers, namely those living in the south of the village. Instead of writing ``getLocation() = "south"`` in all your queries, you could define a new `predicate <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ ``isSouthern``:
This time you only need to consider a specific group of villagers, namely those living in the south of the village. Instead of writing ``getLocation() = "south"`` in all your queries, you could define a new `predicate <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ ``isSouthern``:
.. code-block:: ql
@@ -41,7 +41,7 @@ You can now list all southerners using:
where isSouthern(p)
select p
This is already a nice way to simplify the logic, but we could be more efficient. Currently, the query looks at every ``Person p``, and then restricts to those who satisfy ``isSouthern(p)``. Instead, we could define a new `class <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ ``Southerner`` containing precisely the people we want to consider.
This is already a nice way to simplify the logic, but we could be more efficient. Currently, the query looks at every ``Person p``, and then restricts to those who satisfy ``isSouthern(p)``. Instead, we could define a new `class <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ ``Southerner`` containing precisely the people we want to consider.
.. code-block:: ql

18
docs/language/learn-ql/beginner/cross-the-river.rst
View File

@@ -20,8 +20,8 @@ A solution should be a set of instructions for how to ferry the items, such as "
across the river, and come back with nothing. Then ferry the cabbage across, and come back with ..."
There are lots of ways to approach this problem and implement it in QL. Before you start, make
sure that you are familiar with how to define `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__
and `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ in QL.
sure that you are familiar with how to define `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__
and `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ in QL.
The following walkthrough is just one of many possible implementations, so have a go at writing your
own query too! To find more example queries, see the list :ref:`below <alternatives>`.
@@ -69,7 +69,7 @@ For example, if the man is on the left shore, the goat on the right shore, and t
shore, the state should be ``Left, Right, Left, Left``.
You may find it helpful to introduce some variables that refer to the shore on which the man and the cargo items are. These
temporary variables in the body of a class are called `fields <https://help.semmle.com/QL/ql-handbook/types.html#fields>`__.
temporary variables in the body of a class are called `fields <https://help.semmle.com/QL/ql-language-reference/types.html#fields>`__.
.. container:: toggle
@@ -159,12 +159,12 @@ could ferry the goat back and forth any number of times without ever reaching an
Such a path would have an infinite number of river crossings without ever solving the puzzle.
One way to restrict our paths to a finite number of river crossings is to define a
`member predicate <https://help.semmle.com/QL/ql-handbook/types.html#member-predicates>`__
`member predicate <https://help.semmle.com/QL/ql-language-reference/types.html#member-predicates>`__
``State reachesVia(string path, int steps)``.
The result of this predicate is any state that is reachable from the current state (``this``) via
the given path in a specified finite number of steps.
You can write this as a `recursive predicate <https://help.semmle.com/QL/ql-handbook/recursion.html>`__,
You can write this as a `recursive predicate <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__,
with the following base case and recursion step:
- If ``this`` *is* the result state, then it (trivially) reaches the result state via an
@@ -218,7 +218,7 @@ the given path without revisiting any previously visited states.
Display the results
~~~~~~~~~~~~~~~~~~~
Once you've defined all the necessary classes and predicates, write a `select clause <https://help.semmle.com/QL/ql-handbook/queries.html#select-clauses>`__
Once you've defined all the necessary classes and predicates, write a `select clause <https://help.semmle.com/QL/ql-language-reference/queries.html#select-clauses>`__
that returns the resulting path.
.. container:: toggle
@@ -230,7 +230,7 @@ that returns the resulting path.
.. literalinclude:: river-crossing.ql
:lines: 115-117
The `don't-care expression <https://help.semmle.com/QL/ql-handbook/expressions.html#don-t-care-expressions>`__ (``_``),
The `don't-care expression <https://help.semmle.com/QL/ql-language-reference/expressions.html#don-t-care-expressions>`__ (``_``),
as the second argument to the ``reachesVia`` predicate, represents any value of ``visitedStates``.
For now, the path defined in ``reachesVia`` just lists the order of cargo items to ferry.
@@ -254,12 +254,12 @@ Here are some more example queries that solve the river crossing puzzle:
➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/659603593702729237/>`__
#. This query models the man and the cargo items in a different way, using an
`abstract <https://help.semmle.com/QL/ql-handbook/annotations.html#abstract>`__
`abstract <https://help.semmle.com/QL/ql-language-reference/annotations.html#abstract>`__
class and predicate. It also displays the resulting path in a more visual way.
➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/1025323464423811143/>`__
#. This query introduces `algebraic datatypes <https://help.semmle.com/QL/ql-handbook/types.html#algebraic-datatypes>`__
#. This query introduces `algebraic datatypes <https://help.semmle.com/QL/ql-language-reference/types.html#algebraic-datatypes>`__
to model the situation, instead of defining everything as a subclass of ``string``.
➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/7260748307619718263/>`__

2
docs/language/learn-ql/beginner/crown-the-rightful-heir.rst
View File

@@ -106,7 +106,7 @@ You can translate this into QL as follows:
result = parentOf(ancestorOf(p))
}
As you can see, you have used the predicate ``ancestorOf()`` inside its own definition. This is an example of `recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__.
As you can see, you have used the predicate ``ancestorOf()`` inside its own definition. This is an example of `recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__.
This kind of recursion, where the same operation (in this case ``parentOf()``) is applied multiple times, is very common in QL, and is known as the *transitive closure* of the operation. There are two special symbols ``+`` and ``*`` that are extremely useful when working with transitive closures:

10
docs/language/learn-ql/beginner/find-the-thief.rst
View File

@@ -53,7 +53,7 @@ There is too much information to search through by hand, so you decide to use yo
QL libraries
------------
We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.
We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.
+--------------------+----------------------------------------------------------------------------------------+
| Predicate | Description |
@@ -84,14 +84,14 @@ The villagers answered "yes" to the question "Is the thief taller than 150cm?" T
where t.getHeight() > 150
select t
The first line, ``from Person t``, declares that ``t`` must be a ``Person``. We say that the `type <https://help.semmle.com/QL/ql-handbook/types.html>`__ of ``t`` is ``Person``.
The first line, ``from Person t``, declares that ``t`` must be a ``Person``. We say that the `type <https://help.semmle.com/QL/ql-language-reference/types.html>`__ of ``t`` is ``Person``.
Before you use the rest of your answers in your QL search, here are some more tools and examples to help you write your own QL queries:
Logical connectives
-------------------
Using `logical connectives <https://help.semmle.com/QL/ql-handbook/formulas.html#logical-connectives>`__, you can write more complex queries that combine different pieces of information.
Using `logical connectives <https://help.semmle.com/QL/ql-language-reference/formulas.html#logical-connectives>`__, you can write more complex queries that combine different pieces of information.
For example, if you know that the thief is older than 30 *and* has brown hair, you can use the following ``where`` clause to link two predicates:
@@ -157,7 +157,7 @@ Notice that we have only temporarily introduced the variable ``c`` and we didn't
Note
If you are familiar with logic, you may notice that ``exists`` in QL corresponds to the existential `quantifier <https://help.semmle.com/QL/ql-handbook/formulas.html#quantified-formulas>`__ in logic. QL also has a universal quantifier ``forall(vars | formula 1 | formula 2)`` which is logically equivalent to ``not exists(vars | formula 1 | not formula 2)``.
If you are familiar with logic, you may notice that ``exists`` in QL corresponds to the existential `quantifier <https://help.semmle.com/QL/ql-language-reference/formulas.html#quantified-formulas>`__ in logic. QL also has a universal quantifier ``forall(vars | formula 1 | formula 2)`` which is logically equivalent to ``not exists(vars | formula 1 | not formula 2)``.
The real investigation
----------------------
@@ -218,7 +218,7 @@ You are getting closer to solving the mystery! Unfortunately, you still have qui
More advanced queries
---------------------
What if you want to find the oldest, youngest, tallest, or shortest person in the village? As mentioned in the previous topic, you can do this using ``exists``. However, there is also a more efficient way to do this in QL using functions like ``max`` and ``min``. These are examples of `aggregates <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__.
What if you want to find the oldest, youngest, tallest, or shortest person in the village? As mentioned in the previous topic, you can do this using ``exists``. However, there is also a more efficient way to do this in QL using functions like ``max`` and ``min``. These are examples of `aggregates <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__.
In general, an aggregate is a function that performs an operation on multiple pieces of data and returns a single value as its output. Common aggregates are ``count``, ``max``, ``min``, ``avg`` (average) and ``sum``. The general way to use an aggregate is:

4
docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
View File

@@ -102,7 +102,7 @@ You may also wish to consider methods called by constructors that assign to the
int m_value;
};
This case can be excluded by creating a recursive predicate. The recursive predicate is given a function and a field, then checks whether the function assigns to the field. The predicate runs itself on all the functions called by the function that it has been given. By passing the constructor to this predicate, we can check for assignments of a field in all functions called by the constructor, and then do the same for all functions called by those functions all the way down the tree of function calls. For more information, see "`Recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__" in the QL language reference.
This case can be excluded by creating a recursive predicate. The recursive predicate is given a function and a field, then checks whether the function assigns to the field. The predicate runs itself on all the functions called by the function that it has been given. By passing the constructor to this predicate, we can check for assignments of a field in all functions called by the constructor, and then do the same for all functions called by those functions all the way down the tree of function calls. For more information, see "`Recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__" in the QL language reference.
.. code-block:: ql
@@ -126,7 +126,7 @@ This case can be excluded by creating a recursive predicate. The recursive predi
Refinement 4—simplifying the query
----------------------------------
Finally we can simplify the query by using the transitive closure operator. In this final version of the query, ``c.calls*(fun)`` resolves to the set of all functions that are ``c`` itself, are called by ``c``, are called by a function that is called by ``c``, and so on. This eliminates the need to make a new predicate all together. For more information, see "`Transitive closures <https://help.semmle.com/QL/ql-handbook/recursion.html#transitive-closures>`__" in the QL language reference.
Finally we can simplify the query by using the transitive closure operator. In this final version of the query, ``c.calls*(fun)`` resolves to the set of all functions that are ``c`` itself, are called by ``c``, are called by a function that is called by ``c``, and so on. This eliminates the need to make a new predicate all together. For more information, see "`Transitive closures <https://help.semmle.com/QL/ql-language-reference/recursion.html#transitive-closures>`__" in the QL language reference.
.. code-block:: ql

4
docs/language/learn-ql/go/basic-query-for-go-code.rst
View File

@@ -99,8 +99,8 @@ After the initial ``import`` statement, this simple query comprises three parts
| ``where recv = m.getReceiver() and | Defines a condition on the variables. | ``recv = m.getReceiver()`` states that ``recv`` must be the receiver variable of ``m``. |
| w.writesField(recv.getARead(), f, _) and | | |
| not recv.getType() instanceof PointerType`` | | ``w.writesField(recv.getARead(), f, _)`` states that ``w`` must be a location in the code where field ``f`` of ``recv`` is modified. |
| | | We use a `'don't-care' expression <https://help.semmle.com/QL/ql-handbook/expressions.html#don-t-care-expressions>`__ _ for the |
| | | value that is written to ``f``—the actual value doesn't matter in this query. |
| | | We use a `'don't-care' expression <https://help.semmle.com/QL/ql-language-reference/expressions.html#don-t-care-expressions>`__ ``_``|
| | | for the value that is written to ``f``—the actual value doesn't matter in this query. |
| | | |
| | | ``not recv.getType() instanceof PointerType`` states that ``m`` is not a pointer method. |
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+

2
docs/language/learn-ql/index.rst
View File

@@ -36,4 +36,4 @@ CodeQL is based on a powerful query language called QL. The following topics hel
Further reading
***************
- `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__: A description of important concepts in QL and a formal specification of the QL language.
- `QL language reference <https://help.semmle.com/QL/ql-language-reference/index.html>`__: A description of important concepts in QL and a formal specification of the QL language.

2
docs/language/learn-ql/introduction-to-ql.rst
View File

@@ -159,4 +159,4 @@ Further reading
- To find out more about how to write your own queries, try working through the ":doc:`QL tutorials <beginner/ql-tutorials>`."
- For an overview of the other available resources, see ":doc:`Learning CodeQL <../index>`."
- For a more technical description of the underlying language, see the "`QL language reference <https://help.semmle.com/QL/ql-handbook>`__."
- For a more technical description of the underlying language, see the "`QL language reference <https://help.semmle.com/QL/ql-language-reference>`__."

2
docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
View File

@@ -61,7 +61,7 @@ Notice that we use the predicate ``getType`` (available on all subclasses of ``E
The class ``LoopStmt`` is a common superclass of all loops, including, in particular, ``for`` loops as in our example above. While different kinds of loops have different syntax, they all have a loop condition, which can be accessed through predicate ``getCondition``. We use the reflexive transitive closure operator ``*`` applied to the ``getAChildExpr`` predicate to express the requirement that ``expr`` should be nested inside the loop condition. In particular, it can be the loop condition itself.
The final conjunct in the ``where`` clause takes advantage of the fact that `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ can return more than one value (they are really relations). In particular, ``getAnOperand`` may return *either* operand of ``expr``, so ``expr.getAnOperand().isCompileTimeConstant()`` holds if at least one of the operands is constant. Negating this condition means that the query will only find expressions where *neither* of the operands is constant.
The final conjunct in the ``where`` clause takes advantage of the fact that `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ can return more than one value (they are really relations). In particular, ``getAnOperand`` may return *either* operand of ``expr``, so ``expr.getAnOperand().isCompileTimeConstant()`` holds if at least one of the operands is constant. Negating this condition means that the query will only find expressions where *neither* of the operands is constant.
Generalizing the query
----------------------

12
docs/language/learn-ql/writing-queries/about-codeql-queries.rst
View File

@@ -13,13 +13,13 @@ CodeQL includes queries to find the most relevant and interesting problems for e
You can add custom queries to `custom query packs <https://lgtm.com/help/lgtm/about-queries#what-are-query-packs>`__ to analyze your projects in `LGTM <https://lgtm.com>`__, use them to analyze a database with the "`CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__," or you can contribute to the standard CodeQL queries in our `open source repository on GitHub <https://github.com/github/codeql>`__.
This topic is a basic introduction to query files. You can find more information on writing queries for specific programming languages `here <https://help.semmle.com/QL/learn-ql/>`__, and detailed technical information about QL in the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.
This topic is a basic introduction to query files. You can find more information on writing queries for specific programming languages `here <https://help.semmle.com/QL/learn-ql/>`__, and detailed technical information about QL in the `QL language reference <https://help.semmle.com/QL/ql-language-reference/index.html>`__.
For more information on how to format your code when contributing queries to the GitHub repository, see the `CodeQL style guide <https://github.com/github/codeql/blob/main/docs/ql-style-guide.md>`__.
Basic query structure
*********************
`Queries <https://help.semmle.com/QL/ql-handbook/queries.html>`__ written with CodeQL have the file extension ``.ql``, and contain a ``select`` clause. Many of the existing queries include additional optional information, and have the following structure::
`Queries <https://help.semmle.com/QL/ql-language-reference/queries.html>`__ written with CodeQL have the file extension ``.ql``, and contain a ``select`` clause. Many of the existing queries include additional optional information, and have the following structure::
/**
*
@@ -61,7 +61,7 @@ Query metadata is used to identify your custom queries when they are added to th
Import statements
=================
Each query generally contains one or more ``import`` statements, which define the `libraries <https://help.semmle.com/QL/ql-handbook/modules.html#library-modules>`__ or `modules <https://help.semmle.com/QL/ql-handbook/modules.html>`__ to import into the query. Libraries and modules provide a way of grouping together related `types <https://help.semmle.com/QL/ql-handbook/types.html>`__, `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__, and other modules. The contents of each library or module that you import can then be accessed by the query.
Each query generally contains one or more ``import`` statements, which define the `libraries <https://help.semmle.com/QL/ql-language-reference/modules.html#library-modules>`__ or `modules <https://help.semmle.com/QL/ql-language-reference/modules.html>`__ to import into the query. Libraries and modules provide a way of grouping together related `types <https://help.semmle.com/QL/ql-language-reference/types.html>`__, `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__, and other modules. The contents of each library or module that you import can then be accessed by the query.
Our `open source repository on GitHub <https://github.com/github/codeql>`__ contains the standard CodeQL libraries for each supported language.
When writing your own alert queries, you would typically import the standard library for the language of the project that you are querying, using ``import`` followed by a language:
@@ -80,18 +80,18 @@ You can explore the contents of all the standard libraries in the `CodeQL librar
Optional CodeQL classes and predicates
--------------------------------------
You can customize your analysis by defining your own predicates and classes in the query. For further information, see `Defining a predicate <https://help.semmle.com/QL/ql-handbook/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__.
You can customize your analysis by defining your own predicates and classes in the query. For further information, see `Defining a predicate <https://help.semmle.com/QL/ql-language-reference/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-language-reference/types.html#defining-a-class>`__.
From clause
===========
The ``from`` clause declares the variables that are used in the query. Each declaration must be of the form ``<type> <variable name>``.
For more information on the available `types <https://help.semmle.com/QL/ql-handbook/types.html>`__, and to learn how to define your own types using `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__, see the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.
For more information on the available `types <https://help.semmle.com/QL/ql-language-reference/types.html>`__, and to learn how to define your own types using `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__, see the `QL language reference <https://help.semmle.com/QL/ql-language-reference/index.html>`__.
Where clause
============
The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results. This clause uses `aggregations <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-handbook/formulas.html>`_ to limit the variables of interest to a smaller set, which meet the defined conditions.
The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results. This clause uses `aggregations <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-language-reference/formulas.html>`_ to limit the variables of interest to a smaller set, which meet the defined conditions.
The CodeQL libraries group commonly used predicates for specific languages and frameworks. You can also define your own predicates in the body of the query file or in your own custom modules, as described above.
Select clause

6
docs/language/learn-ql/writing-queries/creating-path-queries.rst
View File

@@ -104,7 +104,7 @@ Generating path explanations
****************************
In order to generate path explanations, your query needs to compute a `path graph <https://en.wikipedia.org/wiki/Path_graph>`__.
To do this you need to define a `query predicate <https://help.semmle.com/QL/ql-handbook/queries.html#query-predicates>`__ called ``edges`` in your query.
To do this you need to define a `query predicate <https://help.semmle.com/QL/ql-language-reference/queries.html#query-predicates>`__ called ``edges`` in your query.
This predicate defines the edge relations of the graph you are computing, and it is used to compute the paths related to each result that your query generates.
You can import a predefined ``edges`` predicate from a path graph module in one of the standard data flow libraries. In addition to the path graph module, the data flow libraries contain the other ``classes``, ``predicates``, and ``modules`` that are commonly used in data flow analysis. The import statement to use depends on the language that you are analyzing.
@@ -151,7 +151,7 @@ The configuration class is accessed by importing the data flow library. This cla
For more information on using the configuration class in your analysis see the sections on global data flow in ":doc:`Analyzing data flow in C/C++ <../cpp/analyzing-data-flow-in-cpp>`" and ":doc:`Analyzing data flow in C# <../csharp/analyzing-data-flow-in-csharp>`."
You can also create a configuration for different frameworks and environments by extending the ``Configuration`` class. For more information, see "`Types <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__" in the QL language reference.
You can also create a configuration for different frameworks and environments by extending the ``Configuration`` class. For more information, see "`Types <https://help.semmle.com/QL/ql-language-reference/types.html#defining-a-class>`__" in the QL language reference.
If you are querying Python code (and you have used ``import semmle.python.security.Paths`` in your query) you should declare ``TaintedPathSource source, TaintedPathSink sink`` in your ``from`` statement. You do not need to declare a ``Configuration`` class as the definitions of the ``TaintedPathSource`` and ``TaintedPathSink`` contain all of the type information that is required::
@@ -163,7 +163,7 @@ Defining flow conditions
************************
The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results.
This clause can use `aggregations <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-handbook/formulas.html>`_ to limit the variables of interest to a smaller set which meet the defined conditions.
This clause can use `aggregations <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-language-reference/formulas.html>`_ to limit the variables of interest to a smaller set which meet the defined conditions.
When writing a path queries, you would typically include a predicate that holds only if data flows from the ``source`` to the ``sink``.

10
docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
View File

@@ -9,9 +9,9 @@ About query performance
This topic offers some simple tips on how to avoid common problems that can affect the performance of your queries.
Before reading the tips below, it is worth reiterating a few important points about CodeQL and the QL language:
- CodeQL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ are evaluated to database `tables <https://en.wikipedia.org/wiki/Table_(database)>`__. Large predicates generate large tables with many rows, and are therefore expensive to compute.
- CodeQL `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ are evaluated to database `tables <https://en.wikipedia.org/wiki/Table_(database)>`__. Large predicates generate large tables with many rows, and are therefore expensive to compute.
- The QL language is implemented using standard database operations and `relational algebra <https://en.wikipedia.org/wiki/Relational_algebra>`__ (such as join, projection, and union). For more information about query languages and databases, see `About the QL language <https://help.semmle.com/QL/learn-ql/about-ql.html>`__.
- Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see "`Evaluation of QL programs <https://help.semmle.com/QL/ql-handbook/evaluations-of-ql-programs.html>`__."
- Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see "`Evaluation of QL programs <https://help.semmle.com/QL/ql-language-reference/evaluations-of-ql-programs.html>`__."
Performance tips
----------------
@@ -54,7 +54,7 @@ To avoid making this mistake, ``this`` should be restricted in the member predic
Use specific types
~~~~~~~~~~~~~~~~~~
"`Types <https://help.semmle.com/QL/ql-handbook/types.html>`__" provide an upper bound on the size of a relation.
"`Types <https://help.semmle.com/QL/ql-language-reference/types.html>`__" provide an upper bound on the size of a relation.
This helps the query optimizer be more effective, so it's generally good to use the most specific types possible. For example::
predicate foo(LoggingCall e)
@@ -90,7 +90,7 @@ Use ``getAQlClass()`` as a debugging tool, but don't include it in the final ver
Avoid complex recursion
~~~~~~~~~~~~~~~~~~~~~~~
"`Recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__" is about self-referencing definitions.
"`Recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__" is about self-referencing definitions.
It can be extremely powerful as long as it is used appropriately.
On the whole, you should try to make recursive predicates as simple as possible.
That is, you should define a *base case* that allows the predicate to *bottom out*, along with a single *recursive call*::
@@ -103,7 +103,7 @@ That is, you should define a *base case* that allows the predicate to *bottom ou
.. pull-quote:: Note
The query optimizer has special data structures for dealing with `transitive closures <https://help.semmle.com/QL/ql-handbook/recursion.html#transitive-closures>`__.
The query optimizer has special data structures for dealing with `transitive closures <https://help.semmle.com/QL/ql-language-reference/recursion.html#transitive-closures>`__.
If possible, use a transitive closure over a simple recursive predicate, as it is likely to be computed faster.
Fold predicates

2
docs/language/reusables/codeql-ref-tools-further-reading.rst
View File

@@ -1,2 +1,2 @@
- "`QL language reference <https://help.semmle.com/QL/ql-handbook>`__"
- "`QL language reference <https://help.semmle.com/QL/ql-language-reference>`__"
- "`CodeQL tools <https://help.semmle.com/codeql/codeql-tools.html>`__"