Skip to content
Queria Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Change requests

Review the diff of a version pushed to a branch before merging it into main

A change request lets you review the diff from main of a version pushed to a branch before merging it into main. You open, review, and merge change requests in the Change requests tab of the dataset page. Change requests of a public dataset are visible to everyone. Change requests of a private dataset, and the list of branches, are shown only to members of the account that owns the dataset.

Require approval

When “Require approval to change main” is turned on in the Change requests tab, fdl push to main is rejected. Members push to a branch and open a change request, and an account admin merges it. Admins can also merge change requests they opened themselves.

Only an account admin can change this setting. When it is off, members can push to main directly as before, and change requests are also available.

Push to a branch

Create a branch from main with fdl branch, clone that branch, and build. Branch names use lowercase letters, digits, ., _ and -, and may be split into levels with /.

REPO=https://data.queria.io/datasets/<handle>/<dataset>/
uvx --from fdl-cli fdl branch $REPO fix-2025
uvx --from fdl-cli fdl clone $REPO .fdl/work.sqlite --branch fix-2025
# write the tables in your build
uvx --from fdl-cli fdl commit .fdl/work.sqlite -m "Add the 2025 figures" --author <name>
uvx --from fdl-cli fdl push .fdl/work.sqlite

fdl push moves the branch you cloned. Further pushes to the same branch update the change requests opened from it.

Open a change request

In the Change requests tab of the dataset page, click New change request, enter the branch, title and description, and click Create. The change request shows the diff from main (tables added or removed, row counts, columns added, removed or retyped, and changed descriptions) and the versions on the branch.

For a table whose data changed, the page shows which column statistics (nulls, distinct values, min and max) differ from main. Click Show row changes to see the rows only in main (removed) and only on the branch (added), up to the first 200 rows. When the table has a primary key (primary_key), a removed and an added row with the same key count as one changed row, and the changed columns are highlighted. Click Query with SQL and choose a template to open a SQL editor that reads the main and branch versions as base and head, so you can aggregate the changes with SQL. Only the templates that apply to the table’s changes are listed.

  • Row diff: the removed and added rows
  • Changed values: for rows with the same primary key, the columns whose values changed, with the values before and after (tables with a primary key only)
  • Added columns and Removed columns: the values of those columns with the primary key
  • Changed column types: for rows with the same primary key, the values that differ before and after the type change, including values that became NULL because they could not be converted (tables with a primary key only)

Open a change request from a fork

Only members of the account that owns a dataset can push to it. A push from anyone else is rejected with the steps to fork. Anyone else forks the public dataset and opens a change request from a branch of the fork.

  1. Click Fork on the dataset page, enter a name for the fork, and click Fork. The name starts as the upstream name; choose another one if you already have a dataset with that name. A public dataset is created in your account, and the latest version of main in the upstream dataset is copied into it. Until the copy finishes, the heading shows “Copying data from the upstream dataset.” The copied data counts toward the storage quota of your account
  2. Create a branch in the fork and push to it. The steps are the same as in “Push to a branch” above, with REPO set to the URL of the fork (https://data.queria.io/datasets/<your handle>/<fork name>/). Keep name in dataset.json as the upstream name
  3. In the Change requests tab of the fork, click New change request, choose the upstream dataset under Merge into, and create it. The change request is created in the upstream dataset

With the CLI:

queria dataset fork <handle>/<dataset>
# after the copy finishes
uvx --from fdl-cli fdl branch https://data.queria.io/datasets/<your handle>/<dataset>/ fix-2025
queria dataset clone <your handle>/<dataset> --branch fix-2025
# write the tables in your build, then run fdl commit and fdl push
queria dataset request create <handle>/<dataset> --head <your handle>/<dataset> --branch fix-2025 --title "Add the 2025 values"

When the change request is created, the versions and data files you added in the fork are copied into the upstream dataset and count toward the storage quota of the upstream account. Later pushes to the same branch update the change request. An admin of the upstream account merges it.

When data is withdrawn from the upstream dataset, the same data is withdrawn from forks (Withdraw data).

Forks are left out of the dataset list and search. Add fork:true to the search box to include them.

Sync a fork

When the upstream dataset has newer versions, the heading of the fork shows “The source dataset has newer versions.” and a Sync button. Only members of the account that owns the fork see them. Clicking Sync copies the latest version of the upstream main into the fork, and main moves to that version when the copy finishes. The copied data counts toward your account’s storage.

If you have pushed your own versions to the fork’s main, the heading shows “The main of this dataset has diverged from the source.” In this case Sync only copies the latest upstream version and main does not move. When the copy finishes, run the fdl merge <version> <name>.sqlite shown in the heading in the folder where you ran fdl clone, and push the result.

Merge

Account admins see the open change requests on the account’s datasets under “Open change requests” on the account page.

When an account admin clicks Merge on the change request, main moves forward to the branch’s version. The published version changes just as it does when fdl push moves main.

If main has been updated since the change request was opened, clicking Merge has Queria merge the branch’s version into main and move main to the merge version. The branch does not change. Tables, rows, and descriptions are combined by the rules of Merging in the FDL specification.

If main and the branch changed the same table or the same row differently, nothing changes and the change request shows the list of conflicting tables and rows. Fix the branch, push it, and click Merge again.

A change request is also marked merged when you run fdl merge locally and fdl push to main, once the branch’s version is in the history of main.

Close a change request you will not merge with Close. The author and account admins can close it, and Reopen opens it again.

Datasets built from code

In a dataset that Apply in GitHub Actions builds from code (a dataset with an apply branch), each Apply run adds a version to the apply branch and merges it into main. If you change descriptions or rows on main, Apply no longer merges into main automatically and opens a change request from the apply branch instead. That change request can conflict with the changes on main. Change the data and descriptions in the GitHub repository. Report errors in the data to the publisher of the source data.

Was this page helpful?