GraphQL examples¶
The GraphQL endpoint provided by cantabular-api-ext supports many use cases. This section
includes a number of examples illustrating how to use the API to access:
the structure and relationships of variables (the codebook) within Cantabular
tabulations of data
reference metadata and localized content.
All the examples below are based on the example microdata dataset supplied with Cantabular.
Codebook queries¶
Request all variables in a dataset¶
Request the name, label and count of categories within all variables in a specific dataset:
query {
dataset(name: "Example") {
variables {
edges {
node {
name
label
categories {
totalCount
}
}
}
}
}
}
Search for variables in a dataset¶
Search within a dataset for the name, label and description of all variables where these match a specific, case-insensitive string:
query {
dataset(name: "Example") {
variables {
search(text: "siblings") {
edges {
node {
name
label
description
}
}
}
}
}
}
Search for categories across all rule variables¶
Find all categories of rule variables in a dataset, together with the name of their associated variable, that match a case-insensitive string. Note that rule variables are often geographic variables.
query {
dataset(name: "Example") {
ruleBase {
isSourceOf {
categorySearch(text: "london") {
edges {
node {
code
label
variable {
name
}
}
}
}
}
}
}
}
Tabular datasets¶
Tabular datasets, that is, those loaded with pre-computed cross-tabulations
rather than with microdata, expose definitions of the tables available within them
on a tables field within the dataset.
Request all tables in a tabular dataset¶
{
dataset(name:"Example-Tabular") {
name
label
tables {
vars
}
}
}
Tabulation queries¶
Request a tabulation including blocked categories¶
Get a tabulation that includes information on any rule variable categories blocked by disclosure rules and their associated observations as nulls. It also includes information on table dimensions and observation type:
query {
dataset(name: "Example") {
table(variables: ["city", "sex", "siblings_3"], redacted: true ) {
obsType {
name label description decimalPlaces
format {
prefix suffix
fillTrailingZeros
multiplier
}
}
dimensions {
categories {
code label
}
variable {
name label
}
}
values
rules {
blocked {
count
categories {
code label
}
}
}
error
}
}
}
Request a tabulation without observations¶
In some circumstances, it may be helpful to execute a tabulation without requesting observations in order to check whether, and to what extent, a query passes disclosure rules.
The error field will be populated if the whole query is blocked by query rules.
query {
dataset(name: "Example") {
table(variables: ["city", "sex", "siblings"]) {
rules {
blocked {
count
}
passed {
count
}
}
error
}
}
}
Accessing reference metadata and localized content¶
In the examples below, all fields within meta are populated with metadata
content for the Cantabular example microdata dataset loaded into cantabular-metadata.
Note that the fields within meta in the examples below are user-defined
and specific to the schema supplied with the Cantabular example microdata dataset. In
a production system, the fields within meta may be different.
Request dataset metadata in Welsh¶
query {
dataset(name: "Example", lang:"cy") {
name
label
description
meta {
methodology {
statement
link
}
sdc {
statement
link
}
units
}
}
}
Request labels and metadata in Welsh for all variables¶
In this example, the integration between cantabular-api-ext and cantabular-metadata
is demonstrated: when cantabular-metadata is running and has been loaded with
variable labels in Welsh, cantabular-api-ext will automatically retrieve them.
query {
dataset(name: "Example", lang: "cy") {
variables {
edges {
node {
name
label
}
}
}
}
}
Request category labels in Welsh for one variable¶
As with the previous example, this query makes use of the integration between
cantabular-api-ext and cantabular-metadata. cantabular-api-ext automatically
integrates Welsh category labels from cantabular-metadata into the response.
query {
dataset(name: "Example", lang: "cy") {
variables(names: ["siblings"]) {
edges {
node {
name
label
categories {
edges {
node {
code
label
}
}
}
}
}
}
}
}
Request service metadata in English and Welsh¶
This query uses GraphQL aliases to differentiate between two queries
for the same field. Values of the lang parameter must be valid BCP 47 language codes.
query {
english: service(lang: "en") {
meta {
contact {
email
phone
name
}
copyright
license
}
}
cymraeg: service(lang: "cy") {
meta {
contact {
email
phone
name
}
copyright
license
}
}
}
Request a list of all service tables¶
This query lists all service tables with their name, dataset name and the variables within that dataset which comprise the table.
query {
service {
tables {
name
datasetName
vars
}
}
}
Request two specific service tables and their metadata¶
This query filters two specific service tables by name and retrieves their associated metadata.
query {
service {
tables(names: ["sex-siblings-city", "age-siblings-city"]) {
name
label
description
datasetName
vars
meta {
keywords
}
}
}
}