Class: Telerivet::DataTable

Inherits:
Entity
  • Object
show all
Defined in:
lib/telerivet/datatable.rb

Overview

Represents a custom data table that can store arbitrary rows.

For example, poll services use data tables to store a row for each response.

DataTables are schemaless -- each row simply stores custom variables. Each variable name is equivalent to a different "column" of the data table. Telerivet refers to these variables/columns as "fields", and automatically creates a new field for each variable name used in a row of the table.

Fields:

- id (string, max 34 characters)
  * ID of the data table
  * Read-only

- name
  * Name of the data table
  * Updatable via API

- num_rows (int)
  * Number of rows in the table. For performance reasons, this number may sometimes be
      out-of-date.
  * Read-only

- show_add_row (bool)
  * Whether to allow adding or importing rows via the web app
  * Updatable via API

- show_stats (bool)
  * Whether to show summary charts (pie charts, bar charts, tables of top values) for
      this data table in the web app
  * Updatable via API

- show_contact_columns (bool)
  * Whether to show 'Contact Name' and 'Phone Number' columns in the web app
  * Updatable via API

- vars (Hash)
  * Custom variables stored for this data table. Variable names may be up to 32
      characters in length and can contain the characters a-z, A-Z, 0-9, and _.
      Values may be strings, numbers, or boolean (true/false).
      String values may be up to 4096 bytes in length when encoded as UTF-8.
      Up to 100 variables are supported per object.
      Setting a variable to null will delete the variable.
  * Updatable via API

- project_id
  * ID of the project this data table belongs to
  * Read-only

- url
  * URL to this data table in the Telerivet web app
  * Read-only

Instance Method Summary collapse

Methods inherited from Entity

#get, #initialize, #load, #set, #set_data, #to_s, #vars

Constructor Details

This class inherits a constructor from Telerivet::Entity

Instance Method Details

#count_rows_by_value(variable) ⇒ Object

Returns the number of rows for each value of a given variable. This can be used to get the total number of responses for each choice in a poll, without making a separate query for each response choice. The return value is an object mapping values to row counts, e.g. {"yes":7,"no":3}

Arguments:

- variable
  * Variable of field to count by.
  * Required

Returns: object



403
404
405
 
# File 'lib/telerivet/datatable.rb', line 403

def count_rows_by_value(variable)
    return @api.do_request("GET", get_base_api_path() + "/count_rows_by_value", {'variable' => variable})
end

#create_row(options = nil) ⇒ Object

Adds a new row to this data table.

Arguments:

- options (Hash)

- contact_id
    * ID of the contact that this row is associated with (if applicable)

- from_number (string)
    * Phone number that this row is associated with (if applicable)

- vars
    * Custom variables and values to set for this data row. Variable names may be up to
        32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.
        Values may be strings, numbers, or boolean (true/false).
        String values may be up to 4096 bytes in length when encoded as UTF-8.
        Up to 100 variables are supported per object.
        Setting a variable to null will delete the variable.

Returns: Telerivet::DataRow



128
129
130
131
 
# File 'lib/telerivet/datatable.rb', line 128

def create_row(options = nil)
    require_relative 'datarow'
    DataRow.new(@api, @api.do_request("POST", get_base_api_path() + "/rows", options))
end

#create_view(options) ⇒ Object

Creates a new view of this data table, defined by a filter on its rows. The view's filter conditions cannot be changed after the view is created (although the view can be renamed or deleted).

Telerivet will automatically store the count of rows matching each data view once a day, making it possible to retrieve historical statistics for the number of rows matching the filter, but only for dates after the view is created.

Arguments:

- options (Hash)
  * Required

- name (string, max 64 characters)
    * Name of the view (must be unique within the data table)
    * Required

- filters (Hash)
    * Key-value pairs of conditions that rows must match to be included in the view. To
        filter by a custom variable, precede the variable name with 'vars.' (conditions on
        custom variables may also be provided as a nested object under a `vars` key, e.g.
        `{"vars": {"q1": "yes"}}`); other supported keys are `id`, `time_created`,
        `time_updated`, `contact_id`, `contact_name`, and `from_number`. Each value is
        either a value to match exactly, or an object with an operator such as `ne`,
        `prefix`, `gte`, `gt`, `lte`, `lt`, `exists`, or `not_exists` as the key (e.g.
        `{"gte": 10}`).
    * Required

Returns: Telerivet::DataView



269
270
271
272
 
# File 'lib/telerivet/datatable.rb', line 269

def create_view(options)
    require_relative 'dataview'
    DataView.new(@api, @api.do_request("POST", get_base_api_path() + "/views", options))
end

#delete ⇒ Object

Permanently deletes the given data table, including all its rows



417
418
419
 
# File 'lib/telerivet/datatable.rb', line 417

def delete()
    @api.do_request("DELETE", get_base_api_path())
end

#get_base_api_path ⇒ Object 



469
470
471
 
# File 'lib/telerivet/datatable.rb', line 469

def get_base_api_path()
    "/projects/#{get('project_id')}/tables/#{get('id')}"
end

#get_fields ⇒ Object

Gets a list of all fields (columns) defined for this data table. The return value is an array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', and 'lookup_key'. (Fields are automatically created any time a DataRow's 'vars' property is updated.)

Returns: array



315
316
317
 
# File 'lib/telerivet/datatable.rb', line 315

def get_fields()
    return @api.do_request("GET", get_base_api_path() + "/fields")
end

#get_row_by_id(row_id) ⇒ Object

Retrieves the row in the given table with the given ID.

Arguments:

- row_id
  * ID of the row
  * Required

Returns: Telerivet::DataRow



180
181
182
183
 
# File 'lib/telerivet/datatable.rb', line 180

def get_row_by_id(row_id)
    require_relative 'datarow'
    DataRow.new(@api, @api.do_request("GET", get_base_api_path() + "/rows/#{row_id}"))
end

#get_view_by_id(view_id) ⇒ Object

Retrieves the view of the given table with the given ID.

Arguments:

- view_id
  * ID of the view
  * Required

Returns: Telerivet::DataView



285
286
287
288
 
# File 'lib/telerivet/datatable.rb', line 285

def get_view_by_id(view_id)
    require_relative 'dataview'
    DataView.new(@api, @api.do_request("GET", get_base_api_path() + "/views/#{view_id}"))
end

#id ⇒ Object 



421
422
423
 
# File 'lib/telerivet/datatable.rb', line 421

def id
    get('id')
end

#import_rows(options) ⇒ Object

Creates and/or updates up to 200 rows in a single API call. When creating or updating a large number of rows, this method is significantly faster than sending a separate API request for each row.

By default, a new row will be created for each item. To update existing rows, set the lookup_key parameter to match rows by ID, contact, or the value of a custom variable.

Arguments:

- options (Hash)
  * Required

- rows (array)
    * Array of up to 200 objects which may contain the properties `vars` (object),
        `contact_id` (string), `from_number` (string), and `id` (string). All properties are
        optional, unless used as a lookup key.
    * Required

- lookup_key
    * The field used to search for a matching row, or 'none' to always create a new row.
        To search by a custom variable, precede the variable name with 'vars.'.
    * Allowed values: none, id, contact_id, vars.variable_name
    * Default: none

Returns: (associative array) - rows (array) * List of objects representing each row, in the same order as provided in the rows parameter in the API request.



164
165
166
167
 
# File 'lib/telerivet/datatable.rb', line 164

def import_rows(options)
    data = @api.do_request("POST", get_base_api_path() + "/import_rows", options)
    return data
end

#init_row_by_id(row_id) ⇒ Object

Initializes the row in the given table with the given ID, without making an API request.

Arguments:

- row_id
  * ID of the row
  * Required

Returns: Telerivet::DataRow



196
197
198
199
 
# File 'lib/telerivet/datatable.rb', line 196

def init_row_by_id(row_id)
    require_relative 'datarow'
    return DataRow.new(@api, {'project_id' => self.project_id, 'table_id' => self.id, 'row_id' => row_id}, false)
end

#init_view_by_id(view_id) ⇒ Object

Initializes the view of the given table with the given ID, without making an API request.

Arguments:

- view_id
  * ID of the view
  * Required

Returns: Telerivet::DataView



301
302
303
304
 
# File 'lib/telerivet/datatable.rb', line 301

def init_view_by_id(view_id)
    require_relative 'dataview'
    return DataView.new(@api, {'project_id' => self.project_id, 'table_id' => self.id, 'view_id' => view_id}, false)
end

#name ⇒ Object 



425
426
427
 
# File 'lib/telerivet/datatable.rb', line 425

def name
    get('name')
end

#name=(value) ⇒ Object 



429
430
431
 
# File 'lib/telerivet/datatable.rb', line 429

def name=(value)
    set('name', value)
end

#num_rows ⇒ Object 



433
434
435
 
# File 'lib/telerivet/datatable.rb', line 433

def num_rows
    get('num_rows')
end

#project_id ⇒ Object 



461
462
463
 
# File 'lib/telerivet/datatable.rb', line 461

def project_id
    get('project_id')
end

#query_rows(options = nil) ⇒ Object

Queries rows in this data table.

Arguments:

- options (Hash)

- time_created (UNIX timestamp)
    * Filter data rows by the time they were created
    * Allowed modifiers: time_created[min], time_created[max]

- contact_id
    * Filter data rows associated with a particular contact

- vars (Hash)
    * Filter data rows by value of a custom variable (e.g. vars[q1], vars[foo], etc.)
    * Allowed modifiers: vars[foo][ne], vars[foo][prefix], vars[foo][not_prefix],
        vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte], vars[foo][min],
        vars[foo][max], vars[foo][exists]

- sort
    * Sort the results based on a field
    * Allowed values: default
    * Default: default

- sort_dir
    * Sort the results in ascending or descending order
    * Allowed values: asc, desc
    * Default: asc

- page_size (int)
    * Number of results returned per page (max 500)
    * Default: 50

- offset (int)
    * Number of items to skip from beginning of result set
    * Default: 0

Returns: Telerivet::APICursor (of Telerivet::DataRow)



100
101
102
103
 
# File 'lib/telerivet/datatable.rb', line 100

def query_rows(options = nil)
    require_relative 'datarow'
    @api.cursor(DataRow, get_base_api_path() + "/rows", options)
end

#query_views(options = nil) ⇒ Object

Queries views of this data table.

Arguments:

- options (Hash)

- name
    * Filter views by name
    * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
        name[lt], name[lte]

- sort
    * Sort the results based on a field
    * Allowed values: default, name
    * Default: default

- sort_dir
    * Sort the results in ascending or descending order
    * Allowed values: asc, desc
    * Default: asc

- page_size (int)
    * Number of results returned per page (max 500)
    * Default: 50

- offset (int)
    * Number of items to skip from beginning of result set
    * Default: 0

Returns: Telerivet::APICursor (of Telerivet::DataView)



233
234
235
236
 
# File 'lib/telerivet/datatable.rb', line 233

def query_views(options = nil)
    require_relative 'dataview'
    @api.cursor(DataView, get_base_api_path() + "/views", options)
end

#save ⇒ Object

Saves any fields that have changed for this data table.



410
411
412
 
# File 'lib/telerivet/datatable.rb', line 410

def save()
    super
end

#set_field_metadata(variable, options) ⇒ Object

Allows customizing how a field (column) is displayed in the Telerivet web app.

The variable path parameter can contain the characters a-z, A-Z, 0-9, and _, and may be up to 32 characters in length.

Arguments:

- variable
  * The variable name of the field to create or update.
  * Required

- options (Hash)
  * Required

- name (string, max 64 characters)
    * Display name for the field

- type (string)
    * Field type
    * Allowed values: text, long_text, secret, phone_number, email, url, audio, date,
        date_time, number, boolean, checkbox, select, radio, route

- order (int)
    * Order in which to display the field

- items (array)
    * Array of up to 100 objects containing `value` and `label` string properties to
        show when type is `select` or `radio`. Each `value` and `label` must be between 1
        and 256 characters in length.
    * Required if type is `select` or `radio`

- readonly (bool)
    * Set to true to prevent editing the field in the Telerivet web app

- lookup_key (bool)
    * Set to true to allow using this field as a lookup key when importing rows via the
        Telerivet web app

Returns: object



360
361
362
 
# File 'lib/telerivet/datatable.rb', line 360

def set_field_metadata(variable, options)
    return @api.do_request("POST", get_base_api_path() + "/fields/#{variable}", options)
end

#show_add_row ⇒ Object 



437
438
439
 
# File 'lib/telerivet/datatable.rb', line 437

def show_add_row
    get('show_add_row')
end

#show_add_row=(value) ⇒ Object 



441
442
443
 
# File 'lib/telerivet/datatable.rb', line 441

def show_add_row=(value)
    set('show_add_row', value)
end

#show_contact_columns ⇒ Object 



453
454
455
 
# File 'lib/telerivet/datatable.rb', line 453

def show_contact_columns
    get('show_contact_columns')
end

#show_contact_columns=(value) ⇒ Object 



457
458
459
 
# File 'lib/telerivet/datatable.rb', line 457

def show_contact_columns=(value)
    set('show_contact_columns', value)
end

#show_stats ⇒ Object 



445
446
447
 
# File 'lib/telerivet/datatable.rb', line 445

def show_stats
    get('show_stats')
end

#show_stats=(value) ⇒ Object 



449
450
451
 
# File 'lib/telerivet/datatable.rb', line 449

def show_stats=(value)
    set('show_stats', value)
end

#update_fields(options) ⇒ Object

Updates metadata for one or more fields (columns) in the data table. Only the specified fields are updated; other fields are not affected.

To delete a field, include an object with the variable and delete properties set (e.g. {"variable": "my_field", "delete": true}). Deleting a field will also clear the corresponding variable on all rows in the table.

Arguments:

- options (Hash)
  * Required

- metadata (array)
    * Array of up to 100 objects describing the fields to create, update, or delete.
        Each object must contain a `variable` property. Only the properties provided for
        each field will be updated.
    * Required

Returns: array



385
386
387
 
# File 'lib/telerivet/datatable.rb', line 385

def update_fields(options)
    return @api.do_request("POST", get_base_api_path() + "/fields", options)
end

#url ⇒ Object 



465
466
467
 
# File 'lib/telerivet/datatable.rb', line 465

def url
    get('url')
end