[Query] Call Context

This document was generated from 'src/documentation/wiki-query.ts' on 2026-07-21, 13:40:52 UTC presenting an overview of flowR's query API (v2.13.1). Please do not edit this file/wiki page directly.

Call-Context Query ^[overview]

Finds all calls in a set of files that matches specified criteria.
This query is requested with the type call-context.

Call context queries can be used to identify calls to specific functions that match criteria of your interest. For now, we support two criteria:

1. Function Name (callName): The function name is specified by a regular expression. This allows you to find all calls to functions that match a specific pattern. Please note, that if you do not use Regex-Anchors, the query will match any function name that contains the given pattern (you can set the callNameExact property to true to automatically add the ^...$ anchors).
2. Call Targets (callTargets): This specifies to what the function call targets. For example, you may want to find all calls to a function that is not defined locally.

Besides this, we provide the following ways to automatically categorize and link identified invocations:

1. Kind (kind): This is a general category that can be used to group calls together. For example, you may want to link all calls to plot to visualize.
2. Subkind (subkind): This is used to uniquely identify the respective call type when grouping the output. For example, you may want to link all calls to ggplot to plot.
3. Linked Calls (linkTo): This links the current call to the last/nested/.. call of the given kind. This way, you can link a call like points to the latest graphics plot etc.
4. Aliases (includeAliases): Consider a case like f <- function_of_interest, do you want calls to f to be included in the results? There is probably no need to combine this with a global call target!

It's also possible to filter the results based on the following properties:

1. File (fileFilter): This allows you to filter the results based on the file in which the call is located. This can be useful if you are only interested in calls in, e.g., specific folders. The fileFilter property is an object made up of two properties:
   • Filter (filter): A regular expression that a node's file attribute must match to be considered.
   • Include Undefined Files (includeUndefinedFiles): If fileFilter is set, but a node's file attribute is not present, should we include it in the results? Defaults to true.
2. Ignore Parameter Values (ignoreParameterValues): Should we ignore default values for parameters in the results?

Re-using the example code from above, the following query attaches all calls to mean to the kind visualize and the subkind text, all calls that start with read_ to the kind input but only if they are not locally overwritten, and the subkind csv-file, and links all calls to points to the last call to plot:

[
  {
    "type": "call-context",
    "callName": "^mean$",
    "kind": "visualize",
    "subkind": "text"
  },
  {
    "type": "call-context",
    "callName": "^read_",
    "kind": "input",
    "subkind": "csv-file",
    "callTargets": "global"
  },
  {
    "type": "call-context",
    "callName": "^points$",
    "kind": "visualize",
    "subkind": "plot",
    "linkTo": {
      "type": "link-to-last-call",
      "callName": "^plot$"
    }
  }
]

Results (prettified and summarized):

Query: call-context (2 ms)
   ╰ input (2 hits):
     ╰ csv-file (2 hits): read_csv('data.csv') (L.6), read_csv('data2.csv') (L.7)
   ╰ visualize (3 hits):
     ╰ text (2 hits): mean(data$x) (L.9), mean(data2$k) (L.19)
     ╰ plot (1 hit): points(data2$x, data2$y) (L.17) with 1 link (plot(data2$x, data2$y) (L.16))
All queries together required ≈24 ms (1ms accuracy, total 25 ms)

Show Detailed Results as Json

The analysis required 24.8 ms (including parsing and normalization and the query) within the generation environment.

In general, the JSON contains the Ids of the nodes in question as they are present in the normalized AST or the dataflow graph of flowR. Please consult the Interface wiki page for more information on how to get those.

{
  "call-context": {
    ".meta": {
      "timing": 2
    },
    "kinds": {
      "input": {
        "subkinds": {
          "csv-file": [
            {
              "id": 16,
              "name": "read_csv",
              "calls": []
            },
            {
              "id": 22,
              "name": "read_csv",
              "calls": []
            }
          ]
        }
      },
      "visualize": {
        "subkinds": {
          "text": [
            {
              "id": 31,
              "name": "mean"
            },
            {
              "id": 87,
              "name": "mean"
            }
          ],
          "plot": [
            {
              "id": 79,
              "name": "points",
              "linkedIds": [
                67
              ]
            }
          ]
        }
      }
    }
  },
  ".meta": {
    "timing": 24
  }
}

As you can see, all kinds and subkinds with the same name are grouped together. Yet, re-stating common arguments and kinds may be cumbersome (although you can already use clever regex patterns). See the Compound Query for a way to structure your queries more compactly if you think it gets too verbose.

Alias Example

Consider the following code:

foo <- my_test_function
foo()
if(u) bar <- foo
bar()
my_test_function()

Now let's say we want to query all uses of the my_test_function:

[
  {
    "type": "call-context",
    "callName": "^my_test_function",
    "includeAliases": true
  }
]

Results (prettified and summarized):

Query: call-context (1 ms)
   ╰ . (2 hits):
     ╰ . (2 hits): foo() (L.2) with 1 alias root (my_test_function (L.1)), bar() (L.4) with 1 alias root (my_test_function (L.1))
All queries together required ≈6 ms (1ms accuracy, total 7 ms)

Show Detailed Results as Json

The analysis required 6.6 ms (including parsing and normalization and the query) within the generation environment.

In general, the JSON contains the Ids of the nodes in question as they are present in the normalized AST or the dataflow graph of flowR. Please consult the Interface wiki page for more information on how to get those.

{
  "call-context": {
    ".meta": {
      "timing": 1
    },
    "kinds": {
      ".": {
        "subkinds": {
          ".": [
            {
              "id": 4,
              "name": "foo",
              "aliasRoots": [
                1
              ]
            },
            {
              "id": 12,
              "name": "bar",
              "aliasRoots": [
                1
              ]
            }
          ]
        }
      }
    }
  },
  ".meta": {
    "timing": 6
  }
}

Implementation Details

Responsible for the execution of the Call-Context Query query is executeCallContextQueries in ./src/queries/catalog/call-context-query/call-context-query-executor.ts.