What "Declarative" Means in Percival's Data Query and Visualization Language

Percival is declarative in the sense that you describe the result you want — a query over a dataset and the visual form it should take — rather than writing out the step-by-step procedure to compute and draw it. According to its own description, Percival is "a declarative data query and visualization language for exploring complex datasets, producing interactive graphics, and sharing results." That single sentence packs in the key design choices: query and visualization live in one language, the output is interactive graphics, and results are meant to be shared. This explanation covers what that means in practice and when the declarative approach helps or hurts.

The core idea: describe the result, not the procedure

In a procedural workflow, you tell the computer how to get somewhere: load the file, filter rows, group by a field, compute an aggregate, then hand the result to a plotting library and configure axes, marks, and scales one call at a time. In a declarative workflow, you state what the result should be — the data relationship you care about and the visual encoding you want — and the language works out the execution.

A useful analogy is the difference between giving someone turn-by-turn directions and telling them the destination. Declarative systems trade fine-grained control over the path for a shorter, more intention-revealing description of the goal.

Why combining query and visualization in one language matters

Most data work today splits across at least two tools: a query language (SQL, a dataframe API) to shape the data, and a separate graphics library to render it. That split creates friction:

• Context switching. You move between two mental models and often two syntaxes.
• Duplication. The fields you selected in the query must be re-referenced when you configure the chart.
• Iteration cost. Changing what you plot often means going back to change the query first.

Percival's premise is that when query and visualization are expressed in the same declarative language, a single description can cover both. You say what data you want and how it should appear, and the two stay in sync because they are written together.

What this changes when exploring complex datasets

Exploration is iterative: you form a hypothesis, look at a result, and revise. A declarative language tends to shorten that loop because each revision is a change to a description of the outcome rather than a rewrite of a pipeline. The stated goals — exploring complex datasets, producing interactive graphics, and sharing results — line up with that: interactivity means the reader can probe the graphic without rerunning your code, and shareability means the description itself can travel with the result.

A concrete scenario

Suppose you want to see how a metric varies across categories in a dataset with many fields. Procedurally, you would filter, aggregate, then build a chart layer by layer. Declaratively, you would describe the relationship (metric by category) and the visual form (say, bars or points), and let the language handle the computation and rendering. The value shows up most when you then want to change the encoding — swap the axis, add a facet, switch mark type — because that is an edit to the description, not a rebuild.

When the declarative approach fits — and when it doesn't

The trade-off is consistent: declarative buys brevity, readability, and faster iteration at the cost of low-level control. If your task is "understand and communicate a data relationship," the declarative model is a good match. If your task is "produce an exact, hand-tuned rendering," a procedural approach may serve you better.

What to keep in mind

The description above establishes Percival's design intent, not its specific syntax, feature set, or limits — those are not detailed in the available source material. Before committing, check the project's own documentation for the actual language constructs, supported data sources, and how interactive graphics are exported or shared. The declarative framing tells you what kind of tool it is; the docs tell you whether it fits your particular dataset and workflow.