What do Contextual Filters filter against?

Question

I've been banging my head against a wall trying to understand contextual filters for about 6 months now so I thought I'd give up and finally ask. Most recently I read this article on cofiguring contextual filters, which renewed my confusion and frustration on this topic.

Normally in query or procedural languages when you filter something, you specify 2 or 3 things;

1. The value to filter (e.g. "blonde")
2. The place to look for the values (e.g. the "hair color" column)
3. Optionally, the operator to use.

My understanding is that contextual filters only use the "equal to" operator, so I'll leave out 3.

For example, if I wanted to filter a nodes table on all nodes whose value in the title column is equal to the contents of the my_title variable, then in SQL I'd write something like this;

SELECT * FROM nodes WHERE title = @my_title

There's a left hand side (title) and right hand side (my_title). But in the Contextual views section of the view I can only pick the dynamic value to check against (the equivalent of my_title) but where do I pick what I'm actually filtering on (ie. the title column)?

As far as I can tell this is telling the filter to filter on the ID of the current page. Which is fine, but what am I filtering? What are the left and right hand operators to the filtering operation?

Answer 1

Generally speaking, a view is used to show data for a list of entities. View filters are used to select (or filter) which entities are handled by the view; contextual filters are used to select the entities basing on the values passed in the URL.

For example, the Files view that comes with Drupal 8 has two pages: one whose path is /admin/content/files and one whose path is /admin/content/files/usage/%.

The second page shows data (the entity label and the entity type for the entity containing a reference to the file; the module managing the file relationship; the number of times the file is used by the entity) for the file whose ID is passed in the view path.

When I visit /admin/content/files/usage/3 on the test site I created, the view shows the following data.

On /admin/content/files/usage/2, the view shows the following data.

Using as another example a default view that is already enabled on /admin/structure/views, the Taxonomy term view has a page shown on /taxonomy/term/% which uses the Content: Has taxonomy term ID contextual filter.

It shows all the nodes using the taxonomy term whose ID is passed in the URL. In the test site I am using, /taxonomy/term/1 shows all the nodes using the taxonomy term whose ID is 1 (the test taxonomy term), while /taxonomy/term/2 shows all the nodes using the taxonomy term whose ID is 2 (the view taxonomy term).

Contextual filters are still filters, as they select (or filter) the entities from which the data is taken. The difference is that their values are passed from the view URL, not from a form like the filters set in the Filter criteria section.

The number of entities from which the data is taken and what entities are handled by the contextual filter is hard-coded in the class implementing the contextual filter: Content: Has taxonomy term ID selects all the nodes using the taxonomy term whose ID is equal to the value passed in the URL, which could be zero or more than one node, while Content: ID selects only the node whose ID is passed in the URL; User: Created selects all the user accounts that have been created at the time passed in the URL. The category of the contextual filter (another value set by the the class implementing the contextual filter), which is shown in the contextual filter name, helps to understand which entities a contextual filter selects: Content: Has taxonomy term ID and Content: ID select nodes, while User: Created selects users.

Answer 2

In Views, if you go into the Settings (/admin/structure/views/settings), you can check the box Show the SQL query to see the magic.

I made a very simple view of content. Here's the SQL query:

SELECT node_field_data.created AS node_field_data_created, node_field_data.nid AS nid
FROM
{node_field_data} node_field_data
WHERE node_field_data.status = '1'
ORDER BY node_field_data_created DESC
LIMIT 11 OFFSET 0

Next I added a contextual filter for Content: ID and accepted the defaults.

In this case, the SQL query does not change. This is because "Display all results for the specified field" is the default for When the filter value is NOT available in the contextual filter settings.

The query only changes if the contextual filter is provided with a value. (To provide a dummy value for testing purposes, you can input a value in Preview with contextual filters.)

Here, I tested by inputting 1 for Preview with contextual filters, which gave me this query:

SELECT node_field_data.created AS node_field_data_created, node_field_data.nid AS nid
FROM
{node_field_data} node_field_data
WHERE ((node_field_data.nid = '1')) AND (node_field_data.status = '1')
ORDER BY node_field_data_created DESC
LIMIT 11 OFFSET 0

"Contextual filters" is a hard-to-understand name, but back in Drupal 6 (as long as I'm remembering right) this was called "Arguments", which makes more sense to me.