Catalog Service

The Catalog service allows users to easily view and update data sets that they have permission to view/edit in Namara.

Prerequisites

Before trying to call any service method on the Namara client, make sure you follow the authorization steps in the README.

Catalog Methods

Below is a list of methods you can call on the Catalog service.

list_all_datasets(filter = {})

Returns an array of Datasets that the user has permission to view in all organizations. You can optionally provide a filter.

# All fields are optional
{
  reference_ids: [string...]
  limit: { value: int32 },
  offset: { value: int32 },
  states: [string...],
  query: { value: string },
  source_ids: [string...],
  topics: { topic_ids: [string...], organization_id: string },
  dataset_ids: [string...],
  organization_ids: [string...]
}

Example

response = namara.list_all_datasets

response.datasets # => [<Dataset_0>, <Dataset_1>, <Dataset_2>]
response.total_count # => 3

# Providing a filter
response = namara.list_all_datasets({ offset: { value: 1 }})

response.datasets # => [<Dataset_1>, <Dataset_2>]
response.total_count # => 2

list_organization_datasets(organization_id, filter = {})

Given an organization_id, returns an array of Datasets the user has permission to view in that organization. You can optionally provide a filter.

# All fields are optional
{
  limit: { value: int32 },
  offset: { value: int32 },
  query: { value: string},
  topics: { topic_ids: [string...], organization_id: string },
  dataset_ids: [string...],
  states: [string...]
  reference_ids: [string...],
  source_ids: [string...],
  topic_ids: [string...]
}

Example

response = namara.list_organization_datasets("some_org_id")

response.datasets # => [<Dataset_1>, <Dataset_2>]
response.total_count # => 2

# Providing a filter
response = namara.list_organization_datasets("some_org_id", { limit: { value: 1 }})

response.datasets # => [<Dataset_1>]
response.total_count # => 1

get_dataset(dataset_id)

Given a dataset_id, returns the Dataset with that id.

Example

dataset = namara.get_dataset("some_dataset_id")

dataset # => Dataset

update_dataset(dataset)

Given a Dataset, updates the dataset in Namara and returns the updated dataset.

Example

dataset = namara.get_dataset("some_dataset_id")

# update description
dataset.description = "This is a fun dataset"

updated_dataset = namara.update_dataset(dataset)
updated_dataset.description # => "This is a fun dataset"

update_properties(dataset, version_id, properties = [])

Given a Dataset, version_id, and an array of properties to update, updates the properties in Namara and returns an array of updated properties.

Example

dataset = namara.get_dataset("some_dataset_id")

props = [{
  id: dataset.versions[0].properties[0].id,
  title: "New Title"
}]

updated_properties = namara.update_properties(dataset, dataset.versions[0].id, props)
updated_properties # => [<Property ... title: "New Title">]

Data Types

Below are a few data types that you will encounter using the Catalog service.

Dataset

Dataset = {
  id: string,
  reference_id: string,
  source_id: string,
  uploader_id: string,
  state: string,
  language: string,
  page_url: string,
  imported_at: Timestamp,
  deprecated_at: Timestamp,
  disposed_at: Timestamp,
  created_at: Timestamp,
  updated_at: Timestamp,
  versions: [Version...],
  exports_disabled: bool
}

Version

Version = {
  id: string,
  dataset_id: string,
  state: string,
  sequence: int32,
  imported_at: Timestamp,
  deprecated_at: Timestamp,
  created_at: Timestamp,
  updated_at: Timestamp,
  properties: [Property...],
  revisions: [Revision...]
}

Revision

Revision = {
  id: string,
  version_id: string,
  warehouse: string,
  state: string,
  storage_table: string,
  imported_at: Timestamp,
  created_at: Timestamp,
  updated_at: Timestamp
}

Property

Property = {
  id: string,
  version_id: string,
  key: string,
  title: string,
  description: string,
  type: string,
  meta: string,
  position: int32
}