-
Notifications
You must be signed in to change notification settings - Fork 13
Query API
This document was generated from 'src/documentation/wiki-query.ts' on 2026-07-25, 12:59:12 UTC presenting an overview of flowR's query API (v2.13.2, using R v4.5.0). Please do not edit this file/wiki page directly.
This page briefly summarizes flowR's query API, represented by the executeQueries function in ./src/queries/query.ts.
Please see the Interface wiki page for more information on how to access this API.
Note
There are many ways to query a dataflow graph created by flowR.
For example, you can use the request-query message
with a running flowR server, or the :query command in the flowR REPL.
Also, check out the flowr-analysis/sample-analyzer-project-query repository for a complete example project using the query API.
Queries are JSON arrays of query objects, each of which uses a type property to specify the query type.
In general, we separate two types of queries:
- Active Queries: Are exactly what you would expect from a query (e.g., the Call-Context Query). They fetch information from the dataflow graph.
- Virtual Queries: Are used to structure your queries (e.g., the Compound Query).
We separate these from a concept perspective.
For now, we support the following active queries (which we will refer to simply as a query):
-
Abstract Interpretation Query (
absint):
Returns the abstract values inferred for every expression or at specific locations. -
Call-Context Query (
call-context):
Finds all calls in a set of files that matches specified criteria. -
Call-Graph Query (
call-graph):
Returns the call graph of the given code. -
Config Query (
config):
Returns the current configuration of flowR. -
Control-Flow Query (
control-flow):
Provides the control-flow of the program. -
Dataflow Cluster Query (
dataflow-cluster):
Calculates and returns all the clusters present in the dataflow graph. -
Dataflow Lens Query (
dataflow-lens):
Returns a simplified view on the dataflow graph, reduced to definitions, uses, and calls. -
Dataflow Query (
dataflow):
Returns the dataflow graph of the given code. -
Dependencies Query (
dependencies):
Returns all direct dependencies (in- and outputs) of a given R script -
Dice Query (
dice):
Reduces the code to the parts that carry information from a given start point to a given end point. -
Does-Call Query (
does-call):
Checks whether a function calls another function matching given constraints. -
Files Query (
files):
Returns the files matching the given criteria. -
Guess Dependency Versions Query (
guess-dep-versions):
Guesses the version range each dependency must have, from declared constraints and actual code usage. -
Happens-Before Query (
happens-before):
Check whether one normalized AST node happens before another in the CFG. -
Id-Map Query (
id-map):
Returns the id-map of the normalized AST of the given code. -
Input Sources Query (
input-sources):
Classify the input sources of function calls -
Inspect Exceptions of Functions Query (
inspect-exception):
Determine whether functions throw exceptions (known to flowR) -
Inspect Higher-Order Functions Query (
inspect-higher-order):
Determine whether functions are higher-order functions -
Inspect Recursive Functions Query (
inspect-recursion):
Determine whether functions are recursive -
Linter Query (
linter):
Lints a given R script for common issues. -
Location Map Query (
location-map):
Returns a simple mapping of ids to their location in the source file -
Normalized AST Query (
normalized-ast):
Returns the normalized AST of the given code. -
Origin Query (
origin):
Retrieve the origin of a variable, function call, ... -
Project Query (
project):
Returns information about the analyzed project -
Provenance Query (
provenance):
Calculate the provenance of a given variable, optionally restricted to its enveloping fdef -
Resolve Value Query (
resolve-value):
Provides access to flowR's value tracking (which is configurable) -
Search Query (
search):
Provides access to flowR's search API -
Signature Query (
signature):
Inspects the signature database: packages, function signatures, source and documentation links. -
Static Slice Query (
static-slice):
Slice the dataflow graph reducing the code to just the parts relevant for the given criteria (backward and forward).
Similarly, we support the following virtual queries:
-
Compound Query (
compound):
Combines multiple queries of the same type into one, specifying common arguments.
Detailed Query Format (Automatically Generated)
Although it is probably better to consult the detailed explanations, if you want to have a look at the schema, here is its description:
-
Queries to run on the file analysis information (in the form of an array) (array)
Valid item types:
-
A virtual or an active query! (alternatives)
-
Supported queries (alternatives)
-
Call context query used to find calls in the dataflow graph (object)
- type [required] The type of the query. (string) Only allows: 'call-context'
- callName [required] Regex regarding the function name! (string)
-
callNameExact [optional] Should we automatically add the
^and$anchors to the regex to make it an exact match? (boolean) -
kind [optional] The kind of the call, this can be used to group calls together (e.g., linking
plottovisualize). Defaults to.(string) -
subkind [optional] The subkind of the call, this can be used to uniquely identify the respective call type when grouping the output (e.g., the normalized name, linking
ggplottoplot). Defaults to.(string) -
callTargets [optional] Call targets the function may have. This defaults to
any. Request this specifically to gain all call targets we can resolve. (string) Only allows: 'global', 'must-include-global', 'local', 'must-include-local', 'any' -
callTargetNamespace [optional] Only keep calls that resolve to (or are explicitly qualified with) this package (e.g.
barto findbar::foo). (string) - ignoreParameterValues [optional] Should we ignore default values for parameters in the results? (boolean)
-
includeAliases [optional] Consider a case like
f <- function_of_interest, do you want uses offto be included in the results? (boolean) -
fileFilter [optional] Filter that, when set, a node's file attribute must match to be considered (object)
- fileFilter [required] Regex that a node's file attribute must match to be considered (string)
-
includeUndefinedFiles [optional] If
fileFilteris set, but a nodesfileattribute isundefined, should we include it in the results? Defaults totrue. (boolean)
-
linkTo [optional] Links the current call to the last call of the given kind. This way, you can link a call like
pointsto the latest graphics plot etc. (alternatives)- (alternatives)
-
Links the current call to the last call of the given kind. This way, you can link a call like
pointsto the latest graphics plot etc. (object)- type [required] The type of the linkTo sub-query. (string) Only allows: 'link-to-last-call'
-
callName [required] Test regarding the function name of the last call. Similar to
callName, strings are interpreted as a regular expression, and string arrays are checked for containment. (alternatives)- (string)
- (array)
Valid item types:
- (string)
- ignoreIf [optional] Should we ignore this (source) call? Currently, there is no well working serialization for this. (function)
- cascadeIf [optional] Should we continue searching after the link was created? Currently, there is no well working serialization for this. (function)
- attachLinkInfo [optional] Additional information to attach to the link. (object)
-
Allows to link nested calls to their parent calls. This way, you can link an
assert_equalcall to the parenttest_thatcall etc. (object)- type [required] The type of the linkTo sub-query. (string) Only allows: 'link-to-nested-call'
-
callName [required] Test regarding the function name of the last call. Similar to
callName, strings are interpreted as a regular expression, and string arrays are checked for containment. (alternatives)- (string)
- (array)
Valid item types:
- (string)
- ignoreIf [optional] Should we ignore this (source) call? Currently, there is no well working serialization for this. (function)
- attachLinkInfo [optional] Additional information to attach to the link. (object)
-
Links the current call to the last call of the given kind. This way, you can link a call like
- (array)
Valid item types:
- (alternatives)
-
Links the current call to the last call of the given kind. This way, you can link a call like
pointsto the latest graphics plot etc. (object)- type [required] The type of the linkTo sub-query. (string) Only allows: 'link-to-last-call'
-
callName [required] Test regarding the function name of the last call. Similar to
callName, strings are interpreted as a regular expression, and string arrays are checked for containment. (alternatives)- (string)
- (array) Valid item types:
- (string)
- ignoreIf [optional] Should we ignore this (source) call? Currently, there is no well working serialization for this. (function)
- cascadeIf [optional] Should we continue searching after the link was created? Currently, there is no well working serialization for this. (function)
- attachLinkInfo [optional] Additional information to attach to the link. (object)
-
Allows to link nested calls to their parent calls. This way, you can link an
assert_equalcall to the parenttest_thatcall etc. (object)- type [required] The type of the linkTo sub-query. (string) Only allows: 'link-to-nested-call'
-
callName [required] Test regarding the function name of the last call. Similar to
callName, strings are interpreted as a regular expression, and string arrays are checked for containment. (alternatives)- (string)
- (array) Valid item types:
- (string)
- ignoreIf [optional] Should we ignore this (source) call? Currently, there is no well working serialization for this. (function)
- attachLinkInfo [optional] Additional information to attach to the link. (object)
-
Links the current call to the last call of the given kind. This way, you can link a call like
- (alternatives)
- (alternatives)
-
The config query retrieves the current configuration of the flowR instance and optionally also updates it. (object)
- type [required] The type of the query. (string) Only allows: 'config'
- update [optional] An optional partial configuration to update the current configuration with before returning it. Only the provided fields will be updated, all other fields will remain unchanged. (object)
-
inspect [optional] An optional
.-separated path (as a string array) to read a single configuration value instead of returning the whole configuration. (array) Valid item types:- (string)
- reset [optional] If true, discard every prior update and revert to the config the analyzer was created with, before returning it. (boolean)
-
The control flow query provides the control flow graph of the analysis, optionally simplified. (object)
- type [required] The type of the query. (string) Only allows: 'control-flow'
-
config [optional] Optional configuration for the control flow query. (object)
-
simplificationPasses The simplification passes to apply to the control flow graph. If unset, the default simplification order will be used. (array)
Valid item types:
- (string) Only allows: 'unique-cf-sets', 'analyze-dead-code', 'remove-dead-code', 'to-basic-blocks'
-
simplificationPasses The simplification passes to apply to the control flow graph. If unset, the default simplification order will be used. (array)
Valid item types:
-
A query to compute the Call Graph of the analyzed project. (object)
- type [required] The type of the query. (string) Only allows: 'call-graph'
- expandLibraryInternals [optional] Expand library/built-in leaf calls into their internal callees via the signature database (default false). (boolean)
-
The dataflow query simply returns the dataflow graph, there is no need to pass it multiple times! (object)
- type [required] The type of the query. (string) Only allows: 'dataflow'
-
Either returns all function definitions alongside whether they are recursive, or just those matching the filters. (object)
- type [required] The type of the query. (string) Only allows: 'does-call'
- queryId [optional] An optional unique identifier for this query, to identify it in the output. (string)
- call The function from which calls are being made. This is a slicing criterion that resolves to a function definition node. (string)
- calls [required] The constraints on which functions are being called. This can be a combination of name-based or id-based constraints, combined with logical operators (and, or, one-of). (object)
- expandLibraryInternals [optional] Expand a reached library/built-in leaf call into its internal callees via the signature database and match constraints against those too (default false). (boolean)
-
The dataflow-lens query returns a simplified view on the dataflow graph (object)
- type [required] The type of the query. (string) Only allows: 'dataflow-lens'
-
The abstract interpretation query retrieves inferred abstract values (object)
- type [required] The type of the query. (string) Only allows: 'absint'
- inference [required] The type of abstract interpretation inference. (string) Only allows: 'df-shape'
-
criteria [optional] The slicing criteria of the nodes to get the inferred abstract values for. (array)
Valid item types:
- (string)
-
The file query finds files in the project based on their roles and path patterns. (object)
- type [required] The type of the query. (string) Only allows: 'files'
-
roles [optional] Optional roles of the files to query. If not provided, all roles are considered. (array)
Valid item types:
- (string) Only allows: 'description', 'namespace', 'news', 'vignette', 'test', 'install', 'data', 'license', 'virtual-env', 'manifest', 'startup', 'environment', 'source', 'other'
- matchesPathRegex [optional] An optional regular expression to match the file paths against. (string)
-
The id map query retrieves the id map from the normalized AST. (object)
- type [required] The type of the query. (string) Only allows: 'id-map'
-
The normalized AST query simply returns the normalized AST, there is no need to pass it multiple times! (object)
- type [required] The type of the query. (string) Only allows: 'normalized-ast'
-
The cluster query calculates and returns all clusters in the dataflow graph. (object)
- type [required] The type of the query. (string) Only allows: 'dataflow-cluster'
-
Slice query used to slice the dataflow graph (object)
- type [required] The type of the query. (string) Only allows: 'static-slice'
-
criteria [required] The slicing criteria to use. (array)
Valid item types:
- (string)
- direction [optional] The direction to slice in. Defaults to backward slicing if unset. (string) Only allows: 'backward', 'forward'
- noReconstruction [optional] Do not reconstruct the slice into readable code. (boolean)
- noMagicComments [optional] Should the magic comments (force-including lines within the slice) be ignored? (boolean)
- inlineSources [optional] Inline resolvable source() calls into the reconstruction so the result is a single self-contained R text. (boolean)
-
inlineFull [optional] Inline all files into the reconstruction, in flowR's loading order and independent of whether they are sourced explicitly; "banner" precedes every file with a banner comment naming it. (alternatives)
- (boolean)
- (string) Only allows: 'banner'
- includeCallees [optional] If set (and slicing backward), continue the slice past a function-definition boundary, also including the definition's binding and call sites. (boolean)
-
Provenance query definition (object)
- type [required] The type of the query. (string) Only allows: 'provenance'
- criterion [required] The slicing criterion to use. (string)
- restrictFdef [required] Whether to stop on fdef boundaries. (boolean)
-
Input Sources query definition (object)
- type [required] The type of the query. (string) Only allows: 'input-sources'
-
criterion [required] The slicing criterion or array of criteria to use. (alternatives)
- (string)
- (array)
Valid item types:
- (string)
-
config [optional] (object)
-
pure [optional] Deterministic/pure functions: functions that preserve constantness of their inputs (e.g., arithmetic, parse). (array)
Valid item types:
- (string)
-
file [optional] Functions that read from the filesystem and produce data (e.g., read.csv, readRDS). (array)
Valid item types:
- (string)
-
tempfile [optional] Functions that produce temporary file paths (sub-type of File; e.g., tempfile, tempdir). (array)
Valid item types:
- (string)
-
net [optional] Functions that fetch data from the network (e.g., download.file, url connections). (array)
Valid item types:
- (string)
-
rand [optional] Functions that produce randomness (e.g., runif, rnorm). (array)
Valid item types:
- (string)
-
system [optional] Functions that execute system commands (e.g., system, system2, shell, pipe). (array)
Valid item types:
- (string)
-
ffi [optional] Functions that call native code via the R FFI (.C, .Call, .Fortran, .External, dyn.load). (array)
Valid item types:
- (string)
-
lang [optional] Functions that produce language objects (e.g., substitute, quote, bquote, expression). (array)
Valid item types:
- (string)
-
options [optional] Functions that access or set global options (e.g., options, getOption). (array)
Valid item types:
- (string)
-
user [optional] Functions that read interactive user input (e.g., file.choose, readline, menu, askYesNo). (array)
Valid item types:
- (string)
-
linkedObjects [optional] Objects a framework provides without a definition in the code, e.g. shiny's input. (array)
Valid item types:
- (object)
- name [required] Name of the object, e.g. input. (string)
- type [required] How reads of the object (or of its fields) are classified. (string) Only allows: 'param', 'file', 'tempfile', 'net', 'rand', 'system', 'ffi', 'lang', 'options', 'user', 'const', 'scope', 'dconst', 'unknown'
-
withParams [optional] Only link the object if the function binding it declares all of these parameters as well. (array)
Valid item types:
- (string)
- (object)
-
linkedEntryPoints [optional] Calls that hand a function to a framework, which binds its objects to the parameters by position. (array)
Valid item types:
- (object)
- call [required] The call taking the function, e.g. shiny::shinyApp. (string)
- argName [required] Name of the argument holding the function. (string)
- argIdx [required] Index of that argument when it is passed positionally. (number)
-
params [required] Which linkedObject the framework binds to each parameter, by position. (array)
Valid item types:
- (string) Only allows: 'null'
- (object)
-
pure [optional] Deterministic/pure functions: functions that preserve constantness of their inputs (e.g., arithmetic, parse). (array)
Valid item types:
-
The dependencies query retrieves and returns the set of all dependencies in the dataflow graph, which includes libraries, sourced files, read data, and written data. (object)
- type [required] The type of the query. (string) Only allows: 'dependencies'
- ignoreDefaultFunctions [optional] Should the set of functions that are detected by default be ignored/skipped? Defaults to false. (boolean)
-
libraryFunctions [optional] The set of library functions to search for. (array)
Valid item types:
- (object)
- name [required] The name of the library function. (string)
- package [optional] The package name of the library function (string)
- argIdx [optional] The index of the argument that contains the library name. (number)
- argName [optional] The name of the argument that contains the library name. (string)
- (object)
-
sourceFunctions [optional] The set of source functions to search for. (array)
Valid item types:
- (object)
- name [required] The name of the library function. (string)
- package [optional] The package name of the library function (string)
- argIdx [optional] The index of the argument that contains the library name. (number)
- argName [optional] The name of the argument that contains the library name. (string)
- (object)
-
readFunctions [optional] The set of read functions to search for. (array)
Valid item types:
- (object)
- name [required] The name of the library function. (string)
- package [optional] The package name of the library function (string)
- argIdx [optional] The index of the argument that contains the library name. (number)
- argName [optional] The name of the argument that contains the library name. (string)
- (object)
-
writeFunctions [optional] The set of write functions to search for. (array)
Valid item types:
- (object)
- name [required] The name of the library function. (string)
- package [optional] The package name of the library function (string)
- argIdx [optional] The index of the argument that contains the library name. (number)
- argName [optional] The name of the argument that contains the library name. (string)
- (object)
-
visualizeFunctions [optional] The set of visualize functions to search for. (array)
Valid item types:
- (object)
- name [required] The name of the library function. (string)
- package [optional] The package name of the library function (string)
- argIdx [optional] The index of the argument that contains the library name. (number)
- argName [optional] The name of the argument that contains the library name. (string)
- (object)
-
testFunctions [optional] The set of test functions to search for. (array)
Valid item types:
- (object)
- name [required] The name of the library function. (string)
- package [optional] The package name of the library function (string)
- argIdx [optional] The index of the argument that contains the library name. (number)
- argName [optional] The name of the argument that contains the library name. (string)
- (object)
-
enabledCategories [optional] A set of flags that determines what types of dependencies are searched for. If unset, all dependency types are searched for. (array)
Valid item types:
- (string)
- additionalCategories [optional] A set of additional, user-supplied dependency categories, whose results will be included in the query return value. (object) Only allows: '[object Object]'
-
The location map query retrieves the location of every id in the ast. (object)
- type [required] The type of the query. (string) Only allows: 'location-map'
-
ids [optional] Optional list of ids to filter the results by. (array)
Valid item types:
- (string)
-
The search query searches the normalized AST and dataflow graph for nodes that match the given search query. (object)
- type [required] The type of the query. (string) Only allows: 'search'
- search [required] The search query to execute. (object)
-
Happens-Before tracks whether a always happens before b. (object)
- type [required] The type of the query. (string) Only allows: 'happens-before'
- a [required] The first slicing criterion. (string)
- b [required] The second slicing criterion. (string)
-
Query to inspect which functions throw exceptions. (object)
- type [required] The type of the query. (string) Only allows: 'inspect-exception'
-
filter [optional] If given, only function definitions that match one of the given slicing criteria are considered. Each criterion can be either
line:column,line@variable-name, or$id, where the latter directly specifies the node id of the function definition to be considered. (array) Valid item types:- [required] (string)
-
Either returns all function definitions alongside whether they are higher-order functions, or just those matching the filters. (object)
- type [required] The type of the query. (string) Only allows: 'inspect-higher-order'
-
filter [optional] If given, only function definitions that match one of the given slicing criteria are considered. Each criterion can be either
line:column,line@variable-name, or$id, where the latter directly specifies the node id of the function definition to be considered. (array) Valid item types:- [required] (string)
-
Either returns all function definitions alongside whether they are recursive, or just those matching the filters. (object)
- type [required] The type of the query. (string) Only allows: 'inspect-recursion'
-
filter [optional] If given, only function definitions that match one of the given slicing criteria are considered. Each criterion can be either
line:column,line@variable-name, or$id, where the latter directly specifies the node id of the function definition to be considered. (array) Valid item types:- [required] (string)
-
The resolve value query used to get definitions of an identifier (object)
- type [required] The type of the query. (string) Only allows: 'resolve-value'
-
criteria [required] The slicing criteria to use. (array)
Valid item types:
- (string)
-
The project query provides information on the analyzed project. (object)
- type [required] The type of the query. (string) Only allows: 'project'
- withDf [optional] Whether to include Dataflow information in the result. (boolean)
-
Inspects the loaded signature database(s): loaded databases, a package, a function, or wildcard matches (optionally filtered by parameter name or required-parameter count). (object)
- type [required] The type of the query. (string) Only allows: 'signature'
- package [optional] The package to inspect (glob wildcards allowed); omit for a summary of the loaded databases. (string)
- function [optional] A function/symbol to inspect (glob wildcards allowed). (string)
- version [optional] A version spec: an exact version, a glob (3.*), a semver range (>=3.0.0, 3.x), or a release-date bound (<=2026, >=2021.05 in YYYY.MM.DD). (string)
-
parameters [optional] Keep only functions that have a parameter matching every one of these names (glob wildcards allowed, position-independent). (array)
Valid item types:
- (string)
-
requiredParameters [optional] Keep only functions with exactly this many required (no-default) parameters, excluding
.... (number) -
callGraph [optional] For a single function, also render its transitive call graph as a mermaid.live link (
--cg). (boolean)
-
The resolve value query used to get definitions of an identifier (object)
- type [required] The type of the query. (string) Only allows: 'origin'
- criterion [required] The slicing criteria to use (string)
-
The linter query lints for the given set of rules and returns the result. (object)
- type [required] The type of the query. (string) Only allows: 'linter'
- format [optional] Print the findings in a machine-readable format instead of the human-readable summary. (string) Only allows: 'text', 'sarif', 'github'
-
rules The rules to lint for. If unset, all rules will be included. (array)
Valid item types:
- (string) Only allows: 'deprecated-functions', 'file-path-validity', 'seeded-randomness', 'absolute-file-paths', 'unused-definitions', 'naming-convention', 'network-functions', 'dataframe-access-validation', 'dead-code', 'useless-loop', 'problematic-inputs', 'stop-call', 'roxygen-arguments', 'software-has-license', 'software-has-tests', 'no-leaked-credentials', 'undefined-symbol', 'syntactically-valid'
- (object)
- name [required] (string) Only allows: 'deprecated-functions', 'file-path-validity', 'seeded-randomness', 'absolute-file-paths', 'unused-definitions', 'naming-convention', 'network-functions', 'dataframe-access-validation', 'dead-code', 'useless-loop', 'problematic-inputs', 'stop-call', 'roxygen-arguments', 'software-has-license', 'software-has-tests', 'no-leaked-credentials', 'undefined-symbol', 'syntactically-valid'
- config (object)
-
Dice query: selects only paths from the given start nodes that reach the given end nodes. (object)
- type [required] The type of the query. (string) Only allows: 'dice'
-
from [required] Slicing criteria for the start of the dice (forward slice seeds). (array)
Valid item types:
- (string)
-
to [required] Slicing criteria for the end of the dice (backward slice seeds). (array)
Valid item types:
- (string)
- noReconstruction [optional] Do not reconstruct the slice into readable code. (boolean)
- noMagicComments [optional] Should the magic comments (force-including lines within the slice) be ignored? (boolean)
- inlineSources [optional] Inline resolvable source() calls into the reconstruction so the result is a single self-contained R text. (boolean)
-
inlineFull [optional] Inline all files into the reconstruction, in flowR's loading order and independent of whether they are sourced explicitly; "banner" precedes every file with a banner comment naming it. (alternatives)
- (boolean)
- (string) Only allows: 'banner'
- includeCallees [optional] If set (and slicing backward), continue the slice past a function-definition boundary, also including the definition's binding and call sites. (boolean)
-
Guesses the possible version range of every dependency from declared constraints and signature-database usage. (object)
- type [required] The type of the query. (string) Only allows: 'guess-dep-versions'
-
packages [optional] Restrict the guess to these packages; omit to guess for every declared and used dependency. (array)
Valid item types:
- (string)
- date [optional] Only consider versions released on or before this day, written YYYY.MM.DD (also YYYY or YYYY.MM). (string)
- maxCandidates [optional] Cap the number of candidate versions listed per dependency. (number)
- maxIterations [optional] Bound both fixpoint loops (mutual transitive refinement and arc consistency). (number)
- clean [optional] Ignore the project declared constraints (DESCRIPTION/lockfile/transitive); guess purely from code usage and the date/R bounds. (boolean)
-
disabled [optional] Exclude these evidence sources from consideration entirely (repl: --disabled followed by their one-letter codes, e.g. --disabled ds for declared+signature). (array)
Valid item types:
- (string) Only allows: 'declared', 'transitive', 'signature', 'date', 'base-r', 'available', 'indirect'
-
explode [optional] Also explode the guessed space into concrete per-dependency version assignments. (object)
- order [optional] Iterate each dependency newest-first (default) or oldest-first. (string) Only allows: 'newest', 'oldest'
- prefer [optional] A version to prefer per dependency when it survives the constraints. (object)
- limit [optional] Cap the number of concrete assignments produced. (number)
-
Call context query used to find calls in the dataflow graph (object)
-
Virtual queries (used for structure) (alternatives)
-
Compound query used to combine queries of the same type (object)
- type [required] The type of the query. (string) Only allows: 'compound'
- query [required] The query to run on the file analysis information. (string)
- commonArguments [required] Common arguments for all queries. (object)
-
arguments [required] Arguments for each query. (array)
Valid item types:
- (object)
-
Compound query used to combine queries of the same type (object)
-
Supported queries (alternatives)
-
A virtual or an active query! (alternatives)
First, consider that you have a file like the following (of course, this is just a simple and artificial example):
library(ggplot)
library(dplyr)
library(readr)
# read data with read_csv
data <- read_csv('data.csv')
data2 <- read_csv('data2.csv')
m <- mean(data$x)
print(m)
data %>%
ggplot(aes(x = x, y = y)) +
geom_point()
plot(data2$x, data2$y)
points(data2$x, data2$y)
print(mean(data2$k))Dataflow Graph of the Example
flowchart LR
1{{"`*#91;RSymbol#93;* **ggplot**
*1.9-14* (**id: 1**)`"}}
%% No edges found for 1
3[["`*#91;RFunctionCall#93;* base#58;#58;**library**
*1.1-15* (**id: 3**)
arg: (1)`"]]
style 3 stroke:red,stroke-width:5px;
built-in:library["`Built-In:
library`"]
style built-in:library stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
5{{"`*#91;RSymbol#93;* **dplyr**
*2.9-13* (**id: 5**)`"}}
%% No edges found for 5
7[["`*#91;RFunctionCall#93;* base#58;#58;**library**
*2.1-14* (**id: 7**)
arg: (5)`"]]
style 7 stroke:red,stroke-width:5px;
9{{"`*#91;RSymbol#93;* **readr**
*3.9-13* (**id: 9**)`"}}
%% No edges found for 9
11[["`*#91;RFunctionCall#93;* base#58;#58;**library**
*3.1-14* (**id: 11**)
arg: (9)`"]]
style 11 stroke:red,stroke-width:5px;
14{{"`*#91;RString#93;* **#39;data.csv#39;**
*6.18-27* (**id: 14**)`"}}
%% No edges found for 14
16[["`*#91;RFunctionCall#93;* **read#95;csv**
*6.9-28* (**id: 16**)
arg: (14)`"]]
12["`*#91;RSymbol#93;* **data**
*6.1-4* (**id: 12**, v: 16)`"]
17[["`*#91;RBinaryOp#93;* base#58;#58;**#60;#45;**
*6.1-28* (**id: 17**)
arg: (12, 16)`"]]
built-in:_-["`Built-In:
#60;#45;`"]
style built-in:_- stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
20{{"`*#91;RString#93;* **#39;data2.csv#39;**
*7.19-29* (**id: 20**)`"}}
%% No edges found for 20
%% Environment of 22 [level: 0]:
%% Built-in
%% 1----------------------------------------
%% library-load: {**ggplot:: library-load** (id: 3, type: Function, def. @3)}
%% 2----------------------------------------
%% library-load: {**dplyr:: library-load** (id: 7, type: Function, def. @7)}
%% 3----------------------------------------
%% library-load: {**readr:: library-load** (id: 11, type: Function, def. @11)}
%% 4----------------------------------------
%% data: {**data** (id: 12, type: Unknown, def. @17)}
22[["`*#91;RFunctionCall#93;* **read#95;csv**
*7.10-30* (**id: 22**)
arg: (20)`"]]
18["`*#91;RSymbol#93;* **data2**
*7.1-5* (**id: 18**, v: 22)`"]
23[["`*#91;RBinaryOp#93;* base#58;#58;**#60;#45;**
*7.1-30* (**id: 23**)
arg: (18, 22)`"]]
26(["`*#91;RSymbol#93;* **data**
*9.11-14* (**id: 26**)`"])
27{{"`*#91;RSymbol#93;* **x**
*9.16* (**id: 27**)`"}}
%% No edges found for 27
29[["`*#91;RAccess#93;* base#58;#58;**$**
*9.11-16* (**id: 29**)
arg: (26, 27)`"]]
built-in:_["`Built-In:
$`"]
style built-in:_ stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
31[["`*#91;RFunctionCall#93;* base#58;#58;**mean**
*9.6-17* (**id: 31**)
arg: (29)`"]]
built-in:mean["`Built-In:
mean`"]
style built-in:mean stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
24["`*#91;RSymbol#93;* **m**
*9.1* (**id: 24**, v: 31)`"]
32[["`*#91;RBinaryOp#93;* base#58;#58;**#60;#45;**
*9.1-17* (**id: 32**)
arg: (24, 31)`"]]
34(["`*#91;RSymbol#93;* **m**
*10.7* (**id: 34**)`"])
36[["`*#91;RFunctionCall#93;* base#58;#58;**print**
*10.1-8* (**id: 36**)
arg: (34)`"]]
built-in:print["`Built-In:
print`"]
style built-in:print stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
38(["`*#91;RSymbol#93;* **data**
*12.1-4* (**id: 38**)`"])
43(["`*#91;RSymbol#93;* **x**
*13.24* (**id: 43**)`"])
%% No edges found for 43
44(["`*#91;RArgument#93;* **x**
*13.20* (**id: 44**)`"])
46(["`*#91;RSymbol#93;* **y**
*13.31* (**id: 46**)`"])
%% No edges found for 46
47(["`*#91;RArgument#93;* **y**
*13.27* (**id: 47**)`"])
48[["`*#91;RFunctionCall#93;* **aes**
*13.16-32* (**id: 48**)
arg: (x (44), y (47))`"]]
built-in:aes["`Built-In:
aes`"]
style built-in:aes stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
50[["`*#91;RFunctionCall#93;* **ggplot**
*13.9-33* (**id: 50**)
arg: (38, 48)`"]]
built-in:ggplot["`Built-In:
ggplot`"]
style built-in:ggplot stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
52[["`*#91;RFunctionCall#93;* **data %#62;%
ggplot(aes(x = x, y = y))**
*12.6-8* (**id: 52**)
arg: (38, 50)`"]]
built-in:___["`Built-In:
%#62;%`"]
style built-in:___ stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
54[["`*#91;RFunctionCall#93;* **geom#95;point**
*14.9-20* (**id: 54**)`"]]
built-in:geom_point["`Built-In:
geom#95;point`"]
style built-in:geom_point stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
55[["`*#91;RBinaryOp#93;* base#58;#58;**#43;**
*12.1-14.20* (**id: 55**)
arg: (52, 54)`"]]
57(["`*#91;RSymbol#93;* **data2**
*16.6-10* (**id: 57**)`"])
58{{"`*#91;RSymbol#93;* **x**
*16.12* (**id: 58**)`"}}
%% No edges found for 58
60[["`*#91;RAccess#93;* base#58;#58;**$**
*16.6-12* (**id: 60**)
arg: (57, 58)`"]]
62(["`*#91;RSymbol#93;* **data2**
*16.15-19* (**id: 62**)`"])
63{{"`*#91;RSymbol#93;* **y**
*16.21* (**id: 63**)`"}}
%% No edges found for 63
65[["`*#91;RAccess#93;* base#58;#58;**$**
*16.15-21* (**id: 65**)
arg: (62, 63)`"]]
67[["`*#91;RFunctionCall#93;* base#58;#58;**plot**
*16.1-22* (**id: 67**)
arg: (60, 65)`"]]
built-in:plot["`Built-In:
plot`"]
style built-in:plot stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
69(["`*#91;RSymbol#93;* **data2**
*17.8-12* (**id: 69**)`"])
70{{"`*#91;RSymbol#93;* **x**
*17.14* (**id: 70**)`"}}
%% No edges found for 70
72[["`*#91;RAccess#93;* base#58;#58;**$**
*17.8-14* (**id: 72**)
arg: (69, 70)`"]]
74(["`*#91;RSymbol#93;* **data2**
*17.17-21* (**id: 74**)`"])
75{{"`*#91;RSymbol#93;* **y**
*17.23* (**id: 75**)`"}}
%% No edges found for 75
77[["`*#91;RAccess#93;* base#58;#58;**$**
*17.17-23* (**id: 77**)
arg: (74, 75)`"]]
79[["`*#91;RFunctionCall#93;* graphics#58;#58;**points**
*17.1-24* (**id: 79**)
arg: (72, 77)`"]]
built-in:points["`Built-In:
points`"]
style built-in:points stroke:gray,fill:gray,stroke-width:2px,opacity:.8;
82(["`*#91;RSymbol#93;* **data2**
*19.12-16* (**id: 82**)`"])
83{{"`*#91;RSymbol#93;* **k**
*19.18* (**id: 83**)`"}}
%% No edges found for 83
85[["`*#91;RAccess#93;* base#58;#58;**$**
*19.12-18* (**id: 85**)
arg: (82, 83)`"]]
87[["`*#91;RFunctionCall#93;* base#58;#58;**mean**
*19.7-19* (**id: 87**)
arg: (85)`"]]
89[["`*#91;RFunctionCall#93;* base#58;#58;**print**
*19.1-20* (**id: 89**)
arg: (87)`"]]
3 -->|"arg"| 1
3 -.->|"reads, calls"| built-in:library
linkStyle 1 stroke:gray;
7 -->|"arg"| 5
7 -.->|"reads, calls"| built-in:library
linkStyle 3 stroke:gray;
11 -->|"arg"| 9
11 -.->|"reads, calls"| built-in:library
linkStyle 5 stroke:gray;
16 -->|"arg"| 14
12 -->|"defined-by"| 16
12 -->|"defined-by"| 17
17 -->|"reads, arg"| 16
17 -->|"returns, arg"| 12
17 -.->|"reads, calls"| built-in:_-
linkStyle 11 stroke:gray;
22 -->|"arg"| 20
18 -->|"defined-by"| 22
18 -->|"defined-by"| 23
23 -->|"reads, arg"| 22
23 -->|"returns, arg"| 18
23 -.->|"reads, calls"| built-in:_-
linkStyle 17 stroke:gray;
26 -->|"reads"| 12
29 -->|"reads, returns, arg"| 26
29 -->|"reads, arg"| 27
29 -.->|"reads, calls"| built-in:_
linkStyle 21 stroke:gray;
31 -->|"reads, arg"| 29
31 -.->|"reads, calls"| built-in:mean
linkStyle 23 stroke:gray;
24 -->|"defined-by"| 31
24 -->|"defined-by"| 32
32 -->|"reads, arg"| 31
32 -->|"returns, arg"| 24
32 -.->|"reads, calls"| built-in:_-
linkStyle 28 stroke:gray;
34 -->|"reads"| 24
36 -->|"reads, returns, arg"| 34
36 -.->|"reads, calls"| built-in:print
linkStyle 31 stroke:gray;
38 -->|"reads"| 12
44 -->|"reads"| 43
47 -->|"reads"| 46
48 -->|"reads, arg, non-standard-evaluation"| 44
48 -->|"reads, arg, non-standard-evaluation"| 47
48 -->|"non-standard-evaluation"| 43
48 -->|"non-standard-evaluation"| 46
48 -.->|"reads, calls"| built-in:aes
linkStyle 39 stroke:gray;
50 -->|"reads, arg"| 48
50 -->|"reads, arg"| 38
50 -.->|"reads, calls"| built-in:ggplot
linkStyle 42 stroke:gray;
52 -->|"arg"| 38
52 -->|"returns, arg"| 50
52 -.->|"reads, calls"| built-in:___
linkStyle 45 stroke:gray;
54 -.->|"reads, calls"| built-in:geom_point
linkStyle 46 stroke:gray;
54 -->|"reads"| 50
55 -->|"reads, arg"| 52
55 -->|"reads, arg"| 54
55 -.->|"reads, calls"| built-in:_
linkStyle 50 stroke:gray;
57 -->|"reads"| 18
60 -->|"reads, returns, arg"| 57
60 -->|"reads, arg"| 58
60 -.->|"reads, calls"| built-in:_
linkStyle 54 stroke:gray;
62 -->|"reads"| 18
65 -->|"reads, returns, arg"| 62
65 -->|"reads, arg"| 63
65 -.->|"reads, calls"| built-in:_
linkStyle 58 stroke:gray;
67 -->|"reads, arg"| 60
67 -->|"reads, arg"| 65
67 -.->|"reads, calls"| built-in:plot
linkStyle 61 stroke:gray;
69 -->|"reads"| 18
72 -->|"reads, returns, arg"| 69
72 -->|"reads, arg"| 70
72 -.->|"reads, calls"| built-in:_
linkStyle 65 stroke:gray;
74 -->|"reads"| 18
77 -->|"reads, returns, arg"| 74
77 -->|"reads, arg"| 75
77 -.->|"reads, calls"| built-in:_
linkStyle 69 stroke:gray;
79 -->|"reads, arg"| 72
79 -->|"reads, arg"| 77
79 -.->|"reads, calls"| built-in:points
linkStyle 72 stroke:gray;
79 -->|"reads"| 67
82 -->|"reads"| 18
85 -->|"reads, returns, arg"| 82
85 -->|"reads, arg"| 83
85 -.->|"reads, calls"| built-in:_
linkStyle 77 stroke:gray;
87 -->|"reads, arg"| 85
87 -.->|"reads, calls"| built-in:mean
linkStyle 79 stroke:gray;
89 -->|"reads, returns, arg"| 87
89 -.->|"reads, calls"| built-in:print
linkStyle 81 stroke:gray;
(The analysis required 6.2 ms (including parse and normalize, using the r-shell engine) within the generation environment. No signature database is mounted for these generated graphs, so library() calls attach no package exports; base-R names are still qualified via the generated base-package store (e.g. acf as stats::acf).)
Additionally, consider that you are interested in all function calls which loads data with read_csv.
A simple regex-based query could look like this: ^read_csv$.
However, this fails to incorporate
- Syntax-based information (comments, strings, used as a variable, called as a higher-order function, ...)
- Semantic information (e.g.,
read_csvis overwritten by a function with the same name) - Context information (e.g., calls like
pointsmay link to the current plot)
To solve this, flowR provides a query API which allows you to specify queries on the dataflow graph.
For the specific use-case stated, you could use the Call-Context Query to find all calls to read_csv which refer functions that are not overwritten.
Just as an example, the following Call-Context Query finds all calls to read_csv that are not overwritten:
[
{
"type": "call-context",
"callName": "^read_csv$",
"callTargets": "global",
"kind": "input",
"subkind": "csv-file"
}
]Results (prettified and summarized):
Query: call-context (1 ms)
╰ input (2 hits):
╰ csv-file (2 hits): read_csv('data.csv') (L.6), read_csv('data2.csv') (L.7)
All queries together required ≈7 ms (1ms accuracy, total 7 ms)
Show Detailed Results as Json
The analysis required 6.9 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": {
"input": {
"subkinds": {
"csv-file": [
{
"id": 16,
"name": "read_csv",
"calls": []
},
{
"id": 22,
"name": "read_csv",
"calls": []
}
]
}
}
}
},
".meta": {
"timing": 7
}
}Every query is explained in detail on its own wiki page, linked from the overviews above.
Currently maintained by Florian Sihler and Oliver Gerstl at Ulm University
Email | GitHub | Penguins | Portfolio
- 🧑💻 Developer Onboarding
- 💻 Setup
- 👓 Overview
- 🪟 Interfacing with flowR
- 🌋 Core
- 🧹 Testing & Linting (Benchmark Page)
⁉️ FAQ- ℹ️ Extra Information