class Telerivet::DataTable

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 row statistics 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
    * Updatable via API

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

Public Instance Methods

count_rows_by_value(variable) click to toggle source

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
# File lib/telerivet/datatable.rb, line 208
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) click to toggle source

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

Returns:

Telerivet::DataRow
# File lib/telerivet/datatable.rb, line 113
def create_row(options = nil)
    require_relative 'datarow'
    DataRow.new(@api, @api.do_request("POST", get_base_api_path() + "/rows", options))
end
delete() click to toggle source

Permanently deletes the given data table, including all its rows

# File lib/telerivet/datatable.rb, line 222
def delete()
    @api.do_request("DELETE", get_base_api_path())
end
get_base_api_path() click to toggle source
# File lib/telerivet/datatable.rb, line 270
def get_base_api_path()
    "/projects/#{get('project_id')}/tables/#{get('id')}"
end
get_fields() click to toggle source

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
# File lib/telerivet/datatable.rb, line 159
def get_fields()
    return @api.do_request("GET", get_base_api_path() + "/fields")
end
get_row_by_id(id) click to toggle source

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

Arguments:

- id
    * ID of the row
    * Required

Returns:

Telerivet::DataRow
# File lib/telerivet/datatable.rb, line 129
def get_row_by_id(id)
    require_relative 'datarow'
    DataRow.new(@api, @api.do_request("GET", get_base_api_path() + "/rows/#{id}"))
end
id() click to toggle source
# File lib/telerivet/datatable.rb, line 226
def id
    get('id')
end
init_row_by_id(id) click to toggle source

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

Arguments:

- id
    * ID of the row
    * Required

Returns:

Telerivet::DataRow
# File lib/telerivet/datatable.rb, line 145
def init_row_by_id(id)
    require_relative 'datarow'
    return DataRow.new(@api, {'project_id' => self.project_id, 'table_id' => self.id, 'id' => id}, false)
end
name() click to toggle source
# File lib/telerivet/datatable.rb, line 230
def name
    get('name')
end
name=(value) click to toggle source
# File lib/telerivet/datatable.rb, line 234
def name=(value)
    set('name', value)
end
num_rows() click to toggle source
# File lib/telerivet/datatable.rb, line 238
def num_rows
    get('num_rows')
end
project_id() click to toggle source
# File lib/telerivet/datatable.rb, line 266
def project_id
    get('project_id')
end
query_rows(options = nil) click to toggle source

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[ne], 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)
# File lib/telerivet/datatable.rb, line 90
def query_rows(options = nil)
    require_relative 'datarow'
    @api.cursor(DataRow, get_base_api_path() + "/rows", options)
end
save() click to toggle source

Saves any fields that have changed for this data table.

Calls superclass method
# File lib/telerivet/datatable.rb, line 215
def save()
    super
end
set_field_metadata(variable, options = nil) click to toggle source

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

Arguments:

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

- options (Hash)

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

  - type (string)
      * Field type
      * Allowed values: text, long_text, number, boolean, email, url, audio, phone_number,
          date, date_time, groups, route, select, buttons, contact

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

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

Returns:

object
# File lib/telerivet/datatable.rb, line 190
def set_field_metadata(variable, options = nil)
    return @api.do_request("POST", get_base_api_path() + "/fields/#{variable}", options)
end
show_add_row() click to toggle source
# File lib/telerivet/datatable.rb, line 242
def show_add_row
    get('show_add_row')
end
show_add_row=(value) click to toggle source
# File lib/telerivet/datatable.rb, line 246
def show_add_row=(value)
    set('show_add_row', value)
end
show_contact_columns() click to toggle source
# File lib/telerivet/datatable.rb, line 258
def show_contact_columns
    get('show_contact_columns')
end
show_contact_columns=(value) click to toggle source
# File lib/telerivet/datatable.rb, line 262
def show_contact_columns=(value)
    set('show_contact_columns', value)
end
show_stats() click to toggle source
# File lib/telerivet/datatable.rb, line 250
def show_stats
    get('show_stats')
end
show_stats=(value) click to toggle source
# File lib/telerivet/datatable.rb, line 254
def show_stats=(value)
    set('show_stats', value)
end