Find or create a new dataset

Find and verify an existing dataset or create a new one.

PUT is the HTTP method for retrieving resources from the Datasets API.

PUT https://api.geckoboard.com/datasets/:id

Where :id is a string to help you identify your dataset from within the application.

Example

curl https://api.geckoboard.com/datasets/sales.by_day \
  -X PUT \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{
  "fields": {
    "amount": {
      "type": "number",
      "name": "Amount",
      "optional": false
    },
    "timestamp": {
      "type": "datetime",
      "name": "Date"
    }
  },
  "unique_by": ["timestamp"]
}'

Response:

{
  "id": "sales.by_day",
  "fields": {
    "amount": { "type": "number", "name": "Amount", "optional": false },
    "timestamp": { "type": "datetime", "name": "Date" }
  },
  "unique_by": ["timestamp"]
}
unique_by
An optional array of one or more field names whose values will be unique across all your records.
fields
an object with keys for each column in your dataset. The value describes the type for that column.

We'll use the findOrCreate method.

gb.datasets.findOrCreate(options, callback)

Example

{
  "id": "sales.by_day",
  "fields": {
    "amount": { "type": "number", "name": "Amount", "optional": false },
    "timestamp": { "type": "datetime", "name": "Time" }
  },
  "unique_by": ["timestamp"]
}
unique_by
An optional array of one or more field names whose values will be unique across all your records.
fields
an object with keys for each column in your dataset. The value describes the type for that column.
Attribute Type Required?
options Object Yes
    id String Yes
  fields Object Yes
      type String Yes
      name String Yes
      optional Boolean No
    unique_by Array No
callback Function No
    error Error | Null Yes
    dataset Undefined Yes

We'll use the find_or_create method.

client.datasets.find_or_create(id, fields: fields)

Example

dataset = client.datasets.find_or_create('sales.by_day', fields: [
  Geckoboard::MoneyField.new(:amount, name: 'Amount', currency_code: 'USD', optional: false),
  Geckoboard::DateTimeField.new(:timestamp, name: 'Time'),
], unique_by: [:timestamp])
unique_by
An optional array of one or more field names whose values will be unique across all your records.
fields
an object with keys for each column in your dataset. The value describes the type for that column.

Available field types:

  • DateField
  • DateTimeField
  • NumberField
  • PercentageField
  • StringField
  • MoneyField

We'll use the find_or_create method.

client.datasets.find_or_create(dataset_id, fields, unique_by)

Example

dataset = client.datasets.find_or_create('sales.by_night', {
  'amount': { 'type': 'number', 'name': 'Amount', 'optional': False },
  'timestamp': { 'type': 'datetime', 'name': 'Time' }
}, ['timestamp'])
unique_by
An optional array of one or more field names whose values will be unique across all your records.
fields
an object with keys for each column in your dataset. The value describes the type for that column.
Attribute Type Required?
  datasets_id str Yes
fields dict Yes
    type str Yes
    name str Yes
    optional boolean Yes
  unique_by Array No

Note

For the full list of available field types, see Schemas and types.

Was this article helpful?

Awesome! 👍  Thanks so much for your feedback!