Referencing resources
Last updated
Was this helpful?
Last updated
Was this helpful?
In many parts of this API, we will be referencing on Redivis, as well as their related dataset or workflow. The API uses a consistent structure to uniquely identify tables, as specified below.
In the simplest case, tables are referenced by their name, alongside the name of the table's workflow or dataset, as well as the name the dataset or workflow owner.
Additionally, to handle whitespace and non-standard characters. You can also provide an to ensure that your references don't break when a table, dataset, or workflow gets renamed.
All tables on Redivis belong to either a dataset or a workflow. All datasets belong to either a user or organization, and all workflows belong to a user.
A table reference reflects this hierarchy, taking the following form:
The ownerName will represent the user or organization that owns the dataset / workflow.
The workflowIdentifier consists of the workflow name, followed by an optional referenceId
prefaced by a colon. The name of the workflow may be .
The datasetIdentifier consists of the dataset name, followed by an optional referenceId
prefaced by a colon. The name of the dataset may be . Additionally, the dataset identifier may contain a sample flag :sample
as well as a version identifier. The version identifier will identify a particular version of the dataset (of the form, v1_0
, the current version current
, or the next (unreleased) version next
. If no version is specified the current version will be used by default.
The user_name will never need to be escaped, as these names can only contain word characters ([A-Za-z0-9_]
). These names are case-insensitive.
Dataset, workflow, and table names can contain a wide array of characters. To facilitate programmatic references, these names can be escaped with the following rules:
All non alpha-numeric and underscore characters in names and version tags are replaced by an underscore (_
) character.
Multiple underscore characters are collapsed into one.
Leading and trailing underscores are removed.
All names are case-insensitive.
For example:
Census dataset: 1940-1980
-> census_dataset_1940_1980
~~Leading and trailing characters.
-> leading_and_trailing_characters
If a name contains colons (:
), periods (.
), or backticks (`
), they must be escaped.
While it is obviously convenient to reference tables, datasets, and workflows by their name, this presents a challenge if these resources get renamed over time. In order to avoid code breakage due to renames, each resource has a 4-character (lowercase, alphanumeric) referenceId associated with it. This identifier will always be unique to the relevant scope — that is, a table's referenceId
is unique across all tables in its dataset / workflow, and the referenceId
of a dataset or workflow is unique to all datasets and workflows for that user.
You can also find dataset-specific information by clicking on API Information link on the dataset overview page:
Finally, the referenceId
is returned as a property on dataset and table resource via the API. Table's also have a qualifiedReference
property, which represents the full reference to the table (owner.dataset|workflow.table
), including all reference ids and version specifiers.
By default this uses the latest version of the dataset. If we want to work with version 1.0:
If we want to work with the 1% sample:
The tableIdentifier consists of the table name, followed by an optional referenceId
prefaced by a colon. The name of the table may be .
One of the easiest ways to find the referenceId is to look at your URL bar. For example, if we navigate to the daily observations table in the GHCN dataset, our URL will be: . Here you can see that the dataset's full identifier is 7br5-41440fjzk
. The referenceId is the first part of this identifier: 7br5
. Similarly, the referenceId for the table is 6fff
.
You can also find this information by for a table, and clicking on the tab for programmatic export information. Make sure the "exact references" box is checked, and you'll see the referenceId included in the template.
We can reference the "Daily observations" table from the as:
Finally, we can provide to prevent things from breaking if a dataset or table is renamed. Make sure also to specify a specific dataset version to avoid changes when a new version is released:
Referencing is quite similar, though workflows don’t have versions or samples: