Run a Database Copy in the Web Client
This page follows the job wizard of the web client for a database run, step by step. Read Database Runs and Database Anonymization first for the concepts.
The Database option appears only when your installation runs the database connector. If you see Database anonymization is not enabled on this deployment, ask your administrator. The web client marks the option as Alpha: the screens and the results can change between releases.
Before You Start
You need two connections: a source to read from and a target to write to. The target must already have the schema of the source: see Requirements for the Target. To try the feature first, click Add demo connections. The wizard offers it in the Read from picker as long as you have no connection yet.
Step 1: Use Case
Choose the use case, as for any job.
Step 2: Name & Input
Under What are you anonymizing?, choose Database. Give the job a name, fill in the job context, and click Create Job.
Step 3: Connect a Database
- In Read from, choose the source connection.
- In Write to, choose the target connection. The picker only offers connections of the same engine as the source. For a demo source, it offers the demo targets.
- Click Test the connections. Avatar opens both from the server and reports what it found. Do not skip this: the checks on an empty target and on a connection that cannot be opened only run once the connections have been tested.
- If the target already holds rows and you want to replace them, check Empty this target before writing. Every row in the tables this copy writes to is deleted first. Only those tables are touched.
Each picker also has New connection and Manage connections, so you can add a connection without leaving the wizard.
Next stays disabled while one of these problems remains:
- a source or a target is not chosen;
- the target is the same connection as the source;
- the target is not empty, and Empty this target before writing is not checked;
- the same target is used for two sources;
- a connection could not be opened;
- the engine is not reachable from this installation.
Several Databases
To copy several databases in one run, click Add another database and choose a second source and target. Do this only when the same individuals are in several databases: the run then gives each individual the same fake identity in every copy.
Adding a database to the run changes every generated name in the other copies too.
Step 3b: Confirm the Schema
Avatar reads the source and proposes a treatment for each table. Nothing is copied and nothing is anonymized at this stage. Discovery starts on its own. If it fails, click Try discovery again.
For each table, choose What happens to this table:
| Option | Result in the target |
|---|---|
| Pseudonymize / anonymize — each column decides which | the table is processed; you choose per variable in step 5 |
| Copy as-is | the rows, unchanged |
| Purge — keep the table, drop the rows | the table, with no rows |
| Ignore — leave it out entirely | no table |
Use the search box, the Filter and Apply to to treat many tables at once.
Open a table to see its variables, its keys (key → table.column) and what classification
proposes for each variable, with the rule or the model that proposed it. The list is read-only:
the choices per variable are made in step 5. A key to a table that you ignore or purge is marked
as having no join left to preserve.
When the run copies several databases, each database has its own tab.
Read a Subset of the Rows
In an open table, Extraction parameters > Rows read limits the number of rows the copy reads. Leave it empty to read every row. The field is offered on tables that are processed or copied.
A table that references another kept table has no Rows read field. It shows Follows the tables it references: it receives only the rows that point at the rows that were read, so the subset stays consistent.
Warnings to Read
- The schema says nothing about …, so they will not be in the copy at all.
- … is copied as it stands, so … arrive with their real values. A classifier had proposed replacing them. Check that this is what you want.
These tables have no rows, so they cannot be anonymized is not a warning but an error, shown in red. Next stays enabled, but the whole run fails when it starts. Set those tables to Copy as-is: an empty table is then copied unchanged.
Step 4: Groups & Identities
The page shows the groups of related tables built from your plan. Each group is one job. A purged or ignored table is in no group. Ignoring or purging a table can split a group in two: the tables on each side of it are no longer linked, and become two jobs.
When the run copies several databases, you can declare a reference table (optional). A reference table says that several tables describe the same individuals, so that each individual keeps one identity everywhere. Click Declare a reference table and answer three questions:
- What is this reference table called? For example
rt_person. - What identifies the person, and what is it called in each database? Choose, for each database, the table and the variable that holds the identifier.
- Which values are replaced? Add the variables to replace, for example
email.
You can also list key values that are not a person, such as 0 or SYSTEM. Click
Show key values to compare a few real values from each source: the key must hold the same
thing in every table. Click Add this reference table to confirm.
With one database, the choices per variable of step 5 are enough.
Step 5: Configure Tables
Each group of related tables has its own tab. For each variable, choose:
| Button | Result |
|---|---|
| Anon | synthetic values, drawn from the distribution |
| Pseudo | fake values of the same kind, applied consistently |
| Freeze | the original values, unchanged |
| Drop | the variable is not in the copy |
Freeze keeps real values in the copy. Use it only for a variable that identifies no individual: see Privacy Risk of Frozen Variables.
Key variables show a key or foreign key label and take no treatment: the run re-issues them and keeps every join working.
Avatar advises parameters for each group before the step is ready.
The Reference Table Tab
If you declared a reference table in step 4, it has its own Reference table tab. There you choose how each of its values is replaced. It is resolved once, before any group runs: each individual gets one replacement, and that value is what every group writes. The variables it owns are left out of the modelling of every group.
In steps 6 and 7, the tab is read-only: a reference table has no links and no k of its own.
Sequences
The web client does not set sequences yet. Set them from the Python client, or in the YAML configuration of the run. The results page shows what the run did to the sequence of each table.
Step 6: Link Datasets
For each group, check the links between its tables, as for a relational database run. A group with one table needs no link. The step is skipped when the whole run has a single table.
Step 7: Configure Job
For each group, set the anonymization parameters
(k, ncp) and the metrics. This step is skipped when no variable is left to anonymize, and the
steps after it are renumbered.
Step 8: Run Job
The page shows the generated configuration (YAML) and an equivalent Python script. Click Run now →.
Read the Results
The anonymized data is in the target database. The job page shows:
- Whole run: the number of tables and rows written to the target, the source and target of each database, the result of each reference table, and one line per group.
- One tab per group: its tasks, the tables asked for and delivered (with their treatment, row count, sequence and what happened to each variable), and the privacy and utility metrics of the group. A table can be marked refused or nothing written. A group where every variable is a key or is pseudonymized has nothing to measure: the page says so, and the tables are still copied to the target.
- Reference table (when you declared one): how many individuals were resolved and from how many rows, how many appear in only one source, the values that disagree between sources, the rows that could not be matched, and the individuals that appeared after the reference table was resolved. Many individuals in only one source usually means that the key does not hold the same values in every table.
- Reports: one Technical Assessment and one Impact Assessment per group, because each group is its own avatarization. Download all reports (.zip) gets them all.
If a table did not reach the target, the page warns that rows referencing it now point at nothing.
Re-run or Cancel
Re-run this group and Re-run every group start the same configuration again. They only write into an empty target: empty the target, or recreate it, first.
Adjust and rerun reloads the whole configuration of the run, including every database of a multi-database run, and opens the wizard at Configure tables. Use it to change a choice and run again.
All three find the source and the target by the name of their connection. If a connection was renamed or deleted since the first run, the re-run cannot find it.
The jobs list shows one entry per database run, with the tasks of every group, and offers Download YAML configuration.
Cancel run stops every group, and Cancel this group stops one. The tables already written stay in the target, so the target may be partially filled. Empty it before you start the run again.