Configuring New Datasets

Data and Metadata Configuration

After the API reads in the global settings file, it reads in the dataset configuration files. These configuration files specify how to connect to the available datasets, their metadata, and some internal parameters, eg. for perturbing and weighting the results.

To add a new table to the API, you need to put its data into a database (if you are using the SQL data interface), and add its dataset configuration file.

Dataset Configuration

The dataset configuration files contain all the information needed by the API to work with a particular table's data. You need one json file for each table you wish to make available to users of the API.

The complete specification is given by the schema protari/dataset_config/dataset_config_schema.yaml in the code. The dataset configuration files are validated against this schema whenever the API is started.

Each file is structured as follows:

While you are getting started, you will probably want to set "requires_permission_to_query": false so that you can query your dataset without authentication.

Here is an example from the protari-sample repository.


Specifying the unit of the unit record data allows downstream applications to present queries and results in a user-friendly way, and helps make sure they do not add results on different units (eg. people, households or businesses).

Currently, the field metadata can be just the field name - it does not have to include the allowed values, its type or a title... but expect this to change in future.


  "metadata": {
    "title": "A human-readable title for the dataset.",
    "description": "A longer description of the dataset.",
    "unit": {
      "singular": "person",
      "plural": "people"
    "fields": [
        "name": "SEX"
        "name": "COUNTRY"
        "name": "POSTCODE"

Of course, such minimal field metadata will not give your users much guidance. Use the following sections to provide more information.

For examples of these features, see dataset_config files for the sample datasets in the protari-setup repository.

Field Metadata

For each accessible field, supply the following metadata:

Numeric data fields require careful configuration - see the separate section on numeric data fields.

Fields that are not listed will not be accessible through the API.

Hierarchical fields

The fields can be structured as a hierarchy, which can help the user interface of downstream applications when there are large numbers of fields. The hierarchy of fields is completely independent of the representation in the database, i.e. "parent" fields in the hierarchy are never requested from the database. Accordingly, a field hierarchy has no effect on the API's aggregation results, because users cannot perform aggregations on the "parent" fields.

Longitudinal fields

If your data has one row for each "unit" (eg. person or household), then you do not have any longitudinal fields. However, if you have one row for each unit for each time period, then the time period is your longitudinal field. In that case, you must tell the API by setting the field's is_longitudinal property to true.

Typically there is at most one longitudinal field (eg. "year"), but the API can handle multiple (eg. with simulated data, the simulation number could be a second longitudinal field).

If there is a longitudinal field, you must also specify which field contains the unit's id in unit_id_name in the metadata.

Value Metadata

For each value, the metadata is:

Sentinel values

Sometimes "sentinel" values (eg. null, 9999 or -1) are used to represent special cases, such as missing data, unlinked data, inapplicable questions, or outliers. (If present, null must be a sentinel, and in fact defaults to is_sentinel: true.)

For numeric fields, when calculating functions like means and sums, it is important that sentinel values are not included. Configure this by explicitly listing the sentinel values of each field, and setting is_sentinel to true for them.


        "name": 9999,
        "is_sentinel": true,
        "title": "Not stated"

You should also specify sentinel values for string fields, so users can count records with non-sentinel values. Values with the name null cannot be used on string fields - use an empty string instead. Empty strings are not automatically assumed to be sentinel values.

Hierarchical values

The values can also be hierarchical, again to help the user interface of downstream applications when the user may need to select from a large number of values. Unlike hierarchical fields, hierarchical values do have an effect on the API's aggregation capability. For example, for a "country of birth" field, you might place regions at the top level, followed by countries. Users can then query how many people are born in each region, not just in each country.

The API does this by replacing the region name in the query with the names of all its child values. It is therefore important that the region names do not appear in the data, because they will not be accessible directly. This is checked by the SQL validation script when the API is started.

Hierarchical values are not allowed on fields containing numeric data. Eg. an integer "age" field could not define any values (eg. "40", "900", or "elderly") to contain other values.

Alternative Metadata Formats

A script is available in the protari-setup repository to generate the field and value metadata from a pair of csv files. Some sample csv files provided in that repository are:

COUNTRY,,Country of Birth,,integer,,,,
DWELL,Dwelling,Dwelling Type,Type of dwelling of usual residence,string,,,,
ROOMS,Dwelling,Number of Rooms,,integer,0,20,,
POSTCODE,,Postcode,Postcode of usual residence,string,,,,poa
AMOUNT,,Dollar Amount,,number,0,100,2,


SEX,TRUE,,,Not stated
COUNTRY,,1100,1000,Australia (including External Territories)
COUNTRY,,1102,1100,Norfolk Island
COUNTRY,,1199,1100,Australian External Territories
COUNTRY,,1201,1000,New Zealand
COUNTRY,,1301,1300,New Caledonia
COUNTRY,,1302,1300,Papua New Guinea
COUNTRY,,1303,1300,Solomon Islands
COUNTRY,TRUE,,,Not stated
ROOMS,TRUE,,,Not stated
ROOMS,TRUE,999,,Not applicable

These files will generate a dataset configuration file containing the following hierarchy:

The protari-setup repository also contains csv files and full dataset configuration files for a sample dataset that includes a longitudinal (ie. date or time) field.

QueryClass Definitions

query_class_definitions is a mapping whose keys are query class names (eg. "aggregation"), which describe how to configure each query class. The key properties are transform_definitions, which sets the dataset-specific parameters for each transform, and run, which specifies which transform to execute for this query class.

Here is an example which uses the standard sql_tbe pipeline:

  "query_class_definitions": {
    "aggregation": {
      "allowed_functions": [
      "run": "sql_tbe_pipeline",
      "transform_definitions": {
        "check_field_exclusions": {
          "parameters": {
            "field_exclusion_rules": [
                "limit": 4
        "tbe_perturb": {
          "parameters": {
            "record_key_name": "RECORD_KEY",
            "bigN": 1766976779,
            "m": [
            "p_filename": "pmatrix1",
            "s_filename": "smatrix1",
            "smallC": 5,
            "smallN": 7
        "get_sql_top_rows": {
          "parameters": {
            "parameters": {
              "number": 4,
              "record_key_name": "{tbe_perturb.record_key_name}",
              "value_tiebreaker_name": "{tbe_perturb.record_key_name}"
        "get_aggregated_sql_data": {
          "parameters": {
            "name_in_db": "sample_table"
        "check_sparsity": {
          "parameters": {
            "a": 0.5,
            "b": 0.75

Allowed functions

An optional list of the allowed functions for this query class. By default, only count is allowed.


The name of the transform to apply for this query class. Must be defined in the settings file. Typically, this is a transform containing a "pipeline" of other transformations.

Transform Definitions


Optional field exclusion rules let you restrict the combinations of fields that can be accessed together, whether as "group by", "where" or "function" (eg. mean or sum) clauses.

Eg. The following configuration would prevent a query which groups by POSTCODE, SEX and ROOMS (due to the second limit, to only 2 of these fields). It would also prevent a query for the mean AMOUNT grouped by DWELL, SEX, COUNTRY (due to the first limit, which only allows 3 fields total in a query).

    "field_exclusion_rules": [
        "limit": 3
        "limit": 2,
        "field_names": ["AMOUNT", "SEX", "ROOMS", "POSTCODE"]

Longitudinal fields are always excluded from the field exclusion rules, ie. they do not count towards the limit of 3 in the above example.

Note that unlike all other transforms at the time of writing, the field exclusion rules are displayed to the user, so that downstream apps can use the field exclusion rules to adjust the available options displayed to the user.


This transform gets the aggregated data from a SQL database.

The SQL database connection string is usually specified in the global settings file, but it can be overridden here too. The only additional parameter required to access the data for a particular dataset is its name in the database, eg.

    "get_aggregated_sql_data": {
        "parameters": {
            "name_in_db": "sample_table"

You can also specify which validation checks should be performed for this dataset when the API is started up, eg. for very large datasets you may wish to switch off some validation checks. Pass the additional parameter validations, eg:

        "parameters": {
            "name_in_db": "sample_dataset_name",
            "validations": ["types", "config-values", "db-values", "db-group-values"]

The list above is the full list, which is the default. If the empty array [] is passed, no validations are performed.


See the Perturbation Algorithms section for an explanation of the available perturbation algorithms, and how to configure them.


The TBE perturbation algorithm needs to know the top contributing rows in order to perturb means and sums. This is achieved by the get_sql_top_rows transform. It takes three parameters:

The standard SQL TBE pipeline sets the record key field to match the TBE transform, and also defaults the tiebreaker field to be the record key field. Either or both of these can be overridden if desired.


The sparsity restriction algorithm is also described in the TBE paper. It consists simply of two thresholds on the ratio of low-count values, above which no results should be returned. If not provided, no threshold is applied.


    "sparsity_thresholds": {
      "a": 0.5,
      "b": 0.75

Data Formats

The data must be stored in a single SQL database table. A simple csv-formatted example that would work with the above metadata files, assuming no perturbation parameters are required, is:


(This is a truncated version of the sample data provided in the protari-setup repository.)

Optionally, you may need the following additional fields:

You might consider creating indices on all fields in the table, to improve the speed of where and group by queries.

If needed, some data cleaning and processing scripts are provided in protari-setup. See its README for details.

Validation checks

When the API is started, the settings and dataset configuration files are validated against their schemas, and any errors reported, as are any conflicting dataset names.

(This validation step can be turned off in the global settings.)

Further, the configuration files are validated against the data in the SQL database – in particular:





Which validations are performed can be controlled by the data interface parameters for each dataset, with the valid names being the headings in the list above.

Suggested directory structure

I recommend creating a new directory following the structure of the protari-sample repository:

    base_config.json        # containing the non-field config for any dataset without its own base_config.json
        base_config.json    # the non-field config for dataset 1

Adjust this as needed if your data or metadata starts in a different format.

You can copy across the scripts and settings.yaml from protari-sample and modify them as needed for your situation. If used unchanged, will: