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 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

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



219
220
221
 
# File 'lib/telerivet/datatable.rb', line 219

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

Returns:

Telerivet::DataRow



113
114
115
116
 
# 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 ⇒ Object

Permanently deletes the given data table, including all its rows



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

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

#get_base_api_path ⇒ Object 



281
282
283
 
# File 'lib/telerivet/datatable.rb', line 281

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



159
160
161
 
# 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) ⇒ Object

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

Arguments:

- id
    * ID of the row
    * Required

Returns:

Telerivet::DataRow



129
130
131
132
 
# 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 ⇒ Object 



237
238
239
 
# File 'lib/telerivet/datatable.rb', line 237

def id
    get('id')
end

#init_row_by_id(id) ⇒ Object

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



145
146
147
148
 
# 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 ⇒ Object 



241
242
243
 
# File 'lib/telerivet/datatable.rb', line 241

def name
    get('name')
end

#name=(value) ⇒ Object 



245
246
247
 
# File 'lib/telerivet/datatable.rb', line 245

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

#num_rows ⇒ Object 



249
250
251
 
# File 'lib/telerivet/datatable.rb', line 249

def num_rows
    get('num_rows')
end

#project_id ⇒ Object 



277
278
279
 
# File 'lib/telerivet/datatable.rb', line 277

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)



90
91
92
93
 
# 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 ⇒ Object

Saves any fields that have changed for this data table.



226
227
228
 
# File 'lib/telerivet/datatable.rb', line 226

def save()
    super
end

#set_field_metadata(variable, options) ⇒ Object

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)
    * 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

  - 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 in the dropdown list when type is `select`. Each `value` and `label` must be
          between 1 and 256 characters in length.
      * Required if type is `select`

  - 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



201
202
203
 
# File 'lib/telerivet/datatable.rb', line 201

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

#show_add_row ⇒ Object 



253
254
255
 
# File 'lib/telerivet/datatable.rb', line 253

def show_add_row
    get('show_add_row')
end

#show_add_row=(value) ⇒ Object 



257
258
259
 
# File 'lib/telerivet/datatable.rb', line 257

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

#show_contact_columns ⇒ Object 



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

def show_contact_columns
    get('show_contact_columns')
end

#show_contact_columns=(value) ⇒ Object 



273
274
275
 
# File 'lib/telerivet/datatable.rb', line 273

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

#show_stats ⇒ Object 



261
262
263
 
# File 'lib/telerivet/datatable.rb', line 261

def show_stats
    get('show_stats')
end

#show_stats=(value) ⇒ Object 



265
266
267
 
# File 'lib/telerivet/datatable.rb', line 265

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