Skip to main content

Ontology

This section is about running operations on ontologies (creating, modifying, duplicating, removing, backup and restoring, etc)

Create a new ontology with a description​

Creates a new ontology with a description associated to it.

Required information for creating an ontology with description (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {ontology} - The name of the new ontology
  • {description} - The new description associated with the ontology. This key can be omitted to create an ontology without a description
CREATE ONTOLOGY `{ontology}` DESCRIPTION = '{description}'

Change the description of an ontology​

Changes the description value of an ontology

Required information for changing the description of an ontology (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {ontology} - The name of the ontology of which to change the description
  • {description} - The new description associated with the ontology
ALTER ONTOLOGY `{ontology}` SET DESCRIPTION = '{description}'

Show ontology configurations​

Shows a list of all configurations for a specific ontology

SHOW CONFIG

Show ontology tags​

Shows a list of all the tags associated with the resources (concepts, properties, ontology views) of a specific ontology

SHOW TAGS

Change the configuration parameters for an ontology​

Change the configuration value for a specific configuration in an ontology. The list of available configuration keys are

  • always_quote_identifier - default value - true - Will always show the quote identifiers in SQL statements. Must be true or false
  • default_transitivity - default value - 3 - The default relationship transitive value (unless explicitly specified)
  • entity_label_cast_type - default value - VARCHAR - The CAST operation for entity label. Must be VARCHAR or NVARCHAR
  • graph_algorithm_output_schema - default value -graph_algorithms_output - The default schema in which the output of graph algorithms persists
  • graph_depth - default value - 1 - The number of hops in relationships to be returned from the dtimbr schema when querying for the metadata of a concept
  • graph_traversal_columns - default value - true - Display the dtimbr schema relationships columns in metadata requests of a concept. Must be true or false
  • target_schema_cache - default value - 48 - The target database cache refresh interval of a schema

Required information for changing the configuration of an ontology (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {config_value} - The value of the config to be set.
  • {config_key_name} - The config key name (must be one from the list above)
UPDATE CONFIG SET value='{config_value}' WHERE name='{config_key_name}'

Backup a specific ontology​

Backup the current state of an ontology. After creating the backup, a version id will be automatically created for the ontology

Required information for creating a backup of an ontology (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {ontology} - The name of the ontology you want to backup
  • {comment} - A description associated with the created backup, this field can be left empty.
BACKUP ONTOLOGY `{ontology}` '{comment}'

Shows a list of backups for ontologies​

Shows a list of created backups of ontologies

SHOW ONTOLOGY BACKUP

Restore a specific ontology by version id​

Restore a backup of an ontology that was created in Timbr.

Required information for restoring a backup (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {ontology} - The name of the ontology you want to restore
  • {version} - The version id of the backup you want to restore
RESTORE ONTOLOGY `{ontology}` '{version}'

Show the export of an ontology in SQL​

Returns a dataset of the Timbr SQL representation of an ontology including the concepts, mappings, views, properties and jobs.

EXPORT ONTOLOGY

Additional Export Ontology Statements​

These statements allow for focused retrieval of ontology components like concepts, mappings, views, properties, or jobs. Each command within this section is designed to return a dataset representing only the requested part of the ontology, offering a more granular approach to data export compared to the broader EXPORT ONTOLOGY command above which includes all aspects of the ontology.

EXPORT ONTOLOGY CONCEPTS 
EXPORT ONTOLOGY MAPPINGS 
EXPORT ONTOLOGY VIEWS
EXPORT ONTOLOGY PROPERTIES 
EXPORT ONTOLOGY JOBS

Show the export of an ontology in OWL​

Returns a dataset of the OWL representation of an ontology

EXPORT ONTOLOGY OWL

Refreshing the cache of an ontology​

Refresh the cache of an ontology with respect to metrics regarding concepts, properties, relationships, queries, users, and roles.

REFRESH ONTOLOGY

Validating the integrity of an ontology​

Validates the integrity of an ontology (concepts, relationships, properties, mappings, views). Will return No response if the validation is successful and no errors are found. If an error is found, results will return with the validation error message.

VALIDATE ONTOLOGY

Duplicate an ontology in the same environment​

Duplicating an ontology in the same environment is like exporting to or importing from an existing ontology. In other words, both the Export and Import commands are identical in function and they only depend on the direction of the export/import

Duplicating an ontology using the Export

Required information for duplicating an ontology using the export command (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {source_ontology} - The name of the ontology you want to duplicate from
  • {overwrite} - Whether or not should overwrite an existing ontology if one with the same name already exists. In order to overwrite you should write OVERWRITE, otherwise you can leave it empty
  • {new_ontology} - The name of the ontology to be created or overwritten. If the ontology doesn't exist a new ontology will be created. If it already exists and the {overwrite} flag is not set, the duplicate will fail unless the {overwrite} flag is set.
EXPORT ONTOLOGY `{source_ontology}` {overwrite} TO `{new_ontology}`

Duplicating an ontology using the Import

Required information for duplicating an ontology using the import command(the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {new_ontology} - The name of the ontology to be created or overwritten. If the ontology doesn't exist a new ontology will be created. If it already exists and the {overwrite} flag is not set, the duplicate will fail unless the {overwrite} flag is set.
  • {overwrite} - Whether or not should overwrite an existing ontology if one with the same name already exists. In order to overwrite you should write OVERWRITE, otherwise you can leave it empty
  • {source_ontology} - The name of the ontology you want to duplicate from
IMPORT ONTOLOGY `{new_ontology}` {overwrite} FROM `{source_ontology}`

Export / Import ontologies between different environments​

The export or import between different environments depends on which instance of Timbr the command is executed in. In other words, both the Export and Import commands are identical in function and they only depend on the direction of the export/import

Exporting an ontology to a remote/external environment

Required information for exporting an ontology to an external instance (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {source_ontology_name} - The name of the ontology you want to export as it's presented in the current Timbr instance
  • {overwrite} - Whether or not should overwrite an existing ontology if one with the same name already exists. In order to overwrite you should write OVERWRITE, otherwise you can leave it empty
  • {hostname} - The hostname of the remote Timbr environment to which you want to export to. This is the hostname of the timbr-server
  • {port} - The port of the remote Timbr environment to which you want to export to. This is the port of the timbr-server
  • {new_ontology_name} - The name of the ontology to be exported to. If it doesn't exist a new ontology will be created. If it already exists and the {overwrite} flag is not set, the export will fail unless the {overwrite} flag is set.
  • {username} - The user name in the remote environment, you can use the user token if you want to connect using a timbr access token.
  • {password} - The password to use with the user name in the remote environment. If you use a token, use the token value as the password.
EXPORT ONTOLOGY {source_ontology_name} {overwrite} TO EXTERNAL URL 'jdbc:hive2://{hostname}:{port}/{new_ontology_name};transportMode=http' USER '{username}' PASSWORD '{password}'

Importing an ontology from a remote/external environment

Required information for importing an ontology from an external instance (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {new_ontology} - The name of the ontology you want to import into. If it does not exist a new ontology will be created. If it already exists and the {overwrite} flag is not set, the impot will fail unless the {overwrite} flag is set.
  • {overwrite} - Whether or not should overwrite an existing ontology if one with the same name already exists. In order to overwrite you should write OVERWRITE, otherwise you can leave it empty
  • {hostname} - The hostname of the remote Timbr environment from which you want to import from. This is the hostname of the timbr-server
  • {port} - The port of the remote Timbr environment to which you want to export to. This is the port of the timbr-server
  • {source_ontology_name} - The name of the ontology from which to import.
  • {username} - The user name in the remote environment, you can use the user token if you want to connect using a timbr access token.
  • {password} - The password to use with the user name in the remote environment. If you use a token, use the token value as the password.
IMPORT ONTOLOGY {new_ontology} {overwrite} FROM EXTERNAL URL 'jdbc:hive2://{hostname}:{port}/{source_ontology_name};transportMode=http' USER '{username}' PASSWORD '{password}'

Adding an existing datasource to an ontology​

Adds an existing datasource to a specific ontology.

Required information for adding a datasource to an ontology (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {ontology} - The name of the ontology as it's presented in Timbr
  • {datasource} - The name of the datasource as it's presented in Timbr
ALTER ONTOLOGY {ontology} ADD DATASOURCE `{datasource}`

Removing an existing datasource from an ontology​

Removes an existing datasource from an ontology. This will not remove the datasource from Timbr.

Required information for removing a datasource from an ontology (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {ontology} - The name of the ontology as it's presented in Timbr
  • {datasource} - The name of the datasource as it's presented in Timbr
ALTER ONTOLOGY `{ontology}` DROP DATASOURCE `{datasource}`

Set active datasource for an ontology​

If your ontology has more than one datasources associated with it, and you want to query either

  1. Concept consisting of a mapping using that datasource
  2. Table in the datasource

Required information for setting an active datasource (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {datasource} - The name of the datasource as it's presented in Timbr

You should set the active datasource for that ontology by running the command

SET active_datasource = '{datasource}'

Removing an ontology​

Removes an ontology from timbr

Required information for removing an ontology (the curly brackets {} should not be an input, they are used only as a variable substitution):

  • {ontology_name} - The name of the ontology as it's presented in Timbr
DROP ONTOLOGY `{ontology_name}`