connect

Create a connection to the server, generating a client and session id.

connect(callback: Function): MapdCon
Parameters
callback (Function) A callback that takes (err, success) as its signature. Returns con singleton on success.
Returns
MapdCon: Object
Example

Connect to a MapD server:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect((err, success) => console.log(success));

   con.sessionId() // ["om9E9Ujgbhl6wIzWgLENncjWsaXRDYLy"]

disconnect

Disconnect from the server then clears the client and session values.

disconnect(callback: Function): MapdCon
Parameters
callback (Function) A callback that takes (err, success) as its signature. Returns con singleton on success.
Returns
MapdCon: Object
Example

Disconnect from the server:

var con = new MapdCon()
.host('localhost')
.port('8080')
.dbName('myDatabase')
.user('foo')
.password('bar')
.connect(); // Create a connection


con.sessionId() // ["om9E9Ujgbhl6wIzWgLENncjWsaXRDYLy"]
con.disconnect((err, con) => console.log(err, con))
con.sessionId() === null;

getFrontendViewsAsync

Get the recent dashboards as a list of TFrontendView objects. These objects contain a value for the view_name property, but not for the view_state property.

getFrontendViewsAsync
Returns
Promise<Array<TFrontendView>>: An array which has all saved dashboards.
Example

Get the list of dashboards from the server:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect(); // Create a connection

con.getFrontendViewsAsync().then((results) => console.log(results))
// [TFrontendView, TFrontendView]

getFrontendViewAsync

Get a dashboard object containing a value for the view_state property. This object contains a value for the view_state property, but not for the view_name property.

getFrontendViewAsync
Parameters
viewName (String) the name of the dashboard
Returns
Promise<Object>: An object that contains all data and metadata related to the dashboard
Example

Get a specific dashboard from the server:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect(); // Create a connection

con.getFrontendViewAsync('dashboard_name').then((result) => console.log(result))
// {TFrontendView}

getServerStatusAsync

Get the status of the server as a TServerStatus object. This includes whether the server is read-only, has backend rendering enabled, and the version number.

getServerStatusAsync
Returns
Promise<Object>:
Example

Get the server status:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect(); // Create a connection

con.getServerStatusAsync().then((result) => console.log(result))
//

createFrontendViewAsync

Add a new dashboard to the server.

createFrontendViewAsync(viewName: String, viewState: String, imageHash: String, metaData: String): Promise
Parameters
viewName (String) the name of the new dashboard
viewState (String) the base64-encoded state string of the new dashboard
imageHash (String) the numeric hash of the dashboard thumbnail
metaData (String) Stringified metaData related to the view
Returns
Promise: Returns empty if success
Example

Add a new dashboard to the server:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect();

 con.createFrontendViewAsync('newSave', 'viewstateBase64', null, 'metaData').then(res => console.log(res))

deleteFrontendViewAsync

Delete a dashboard object containing a value for the view_state property.

deleteFrontendViewAsync
Parameters
viewName (String) the name of the dashboard
Returns
Promise<String>: Name of dashboard successfully deleted
Example

Delete a specific dashboard from the server:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect(); // Create a connection

con.deleteFrontendViewAsync('dashboard_name').then(res => console.log(res))

createLinkAsync

Create a short hash to make it easy to share a link to a specific dashboard.

createLinkAsync(viewState: String, metaData: String): Promise<Array<String>>
Parameters
viewState (String) the base64-encoded state string of the new dashboard
metaData (String) Stringified metaData related to the link
Returns
Promise<Array<String>>: link - A short hash of the dashboard used for URLs
Example

Create a link to the current state of a dashboard:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect();

con.createLinkAsync("eyJuYW1lIjoibXlkYXNoYm9hcmQifQ==", 'metaData').then(res => console.log(res));
// ["28127951"]

getLinkViewAsync

Get a fully-formed dashboard object from a generated share link. This object contains the given link for the view_name property,

getLinkViewAsync
Parameters
link (String) the short hash of the dashboard, see createLink
Returns
Promise<Object>: Object of the dashboard and metadata
Example

Get a dashboard from a link:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect();

con.getLinkViewAsync('28127951').then(res => console.log(res))
//  {
//    "view_name": "28127951",
//    "view_state": "eyJuYW1lIjoibXlkYXNoYm9hcmQifQ==",
//    "image_hash": "",
//    "update_time": "2017-04-28T21:34:01Z",
//    "view_metadata": "metaData"
//  }

detectColumnTypesAsync

Asynchronously get the data from an importable file, such as a .csv or plaintext file with a header.

detectColumnTypesAsync(fileName: String, copyParams: TCopyParams): Promise<TDetectResult>
Parameters
fileName (String) the name of the importable file
copyParams (TCopyParams) see TCopyParams
Returns
Promise<TDetectResult>: An object which has copy_params and row_set
Example

Get data from table_data.csv:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect();

var copyParams = new TCopyParams();
con.detectColumnTypesAsync('table_data.csv', copyParams).then(res => console.log(res))
// TDetectResult {row_set: TRowSet, copy_params: TCopyParams}

query

Submit a query to the database and process the results.

query(query: String, options: Object, callback: Function): Object
Parameters
query (String) The query to perform
options (Object) the options for the query
callback (Function) that takes (err, result) => result
Returns
Object: The result of the query
Example

create a query

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect();

var query = "SELECT count(*) AS n FROM tweets_nov_feb WHERE country='CO'";
var options = {};

con.query(query, options, function(err, result) {
       console.log(result)
     });

queryAsync

queryAsync
Deprecated: will default to query

validateQuery

Submit a query to validate whether the backend can create a result set based on the SQL statement.

validateQuery(query: String): Promise<Object>
Parameters
query (String) The query to perform
Returns
Promise<Object>: The result of whether the query is valid
Example

create a query

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect();

var query = "SELECT count(*) AS n FROM tweets_nov_feb WHERE country='CO'";

con.validateQuery(query).then(res => console.log(res))

// [{
//    "name": "n",
//    "type": "INT",
//    "is_array": false,
//    "is_dict": false
//  }]

getTablesAsync

Get the names of the databases that exist on the current session's connectdion.

getTablesAsync(): Promise<Array<Object>>
Returns
Promise<Array<Object>>: list of table objects containing the label and table names.
Example

Get the list of tables from a connection:

var tables = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect()

 con.getTablesAsync().then(res => console.log(res))

 //  [{
 //    label: 'obs', // deprecated property
 //    name: 'myDatabaseName'
 //   },
 //  ...]

invertDatumTypes

Create an array-like object from TDatumType by flipping the string key and numerical value around.

invertDatumTypes(): Undefined
Returns
Undefined: This function does not return anything

getFields

Get a list of field objects for a given table.

getFields(tableName: String, callback: Function): Array<Object>
Parameters
tableName (String) name of table containing field names
callback (Function) (err, results)
Returns
Array<Object>: fields - the formmatted list of field objects
Example

Get the list of fields from a specific table:

var tables = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect()
  .getTables();

con.getFields('flights', (err, res) => console.log(res))
// [{
  name: 'fieldName',
  type: 'BIGINT',
  is_array: false,
  is_dict: false
}, ...]

createTableAsync

Create a table and persist it to the backend.

createTableAsync
Parameters
tableName (String) desired name of the new table
rowDescObj (Array<TColumnType>) fields of the new table
tableType (Number<TTableType>) the types of tables a user can import into the db
Returns
Promise<undefined>: it will either catch an error or return undefined on success
Example

Create a new table:

var result = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect()

 con.createTable('mynewtable', [TColumnType, TColumnType, ...], 0).then(res => console.log(res));
 // undefined

importTableAsync

Import a delimited table from a file.

importTableAsync
Parameters
tableName (String) desired name of the new table
fileName (String)
copyParams (TCopyParams) see TCopyParams
headers (Array<TColumnType>) -- a colleciton of metadata related to the table headers

importTableGeoAsync

Import a geo table from a file.

importTableGeoAsync
Parameters
tableName (String) desired name of the new table
fileName (String)
copyParams (TCopyParams) see TCopyParams
headers (Array<TColumnType>) -- a colleciton of metadata related to the table headers

renderVega

Use for backend rendering. This method will fetch a PNG image that is a render of the vega json object.

renderVega(widgetid: Number, vega: String, options: Object, callback: Function): Image
Parameters
widgetid (Number) the widget id of the calling widget
vega (String) the vega json
options (Object) the options for the render query
Name Description
options.compressionLevel Number the png compression level. range 1 (low compression, faster) to 10 (high compression, slower). Default 3.
callback (Function) takes (err, success) as its signature. Returns con singleton on success.
Returns
Image: Base 64 Image

getResultRowForPixel

Used primarily for backend rendered maps, this method will fetch the row for a specific table that was last rendered at a pixel.

getResultRowForPixel(widgetId: any, pixel: TPixel, tableColNamesMap: Object, callbacks: Array<Function>, pixelRadius: Number?, Number: widgetId, tableName: String)
Parameters
widgetId (any)
pixel (TPixel) the pixel (lower left-hand corner is pixel (0,0))
tableColNamesMap (Object) object of tableName -> array of col names
callbacks (Array<Function>)
pixelRadius (Number? = 2) the radius around the primary pixel to search
Number (widgetId) the widget id of the caller
tableName (String) the table containing the geo data

processPixelResults

Formats the pixel results into the same pattern as textual results.

processPixelResults(callbacks: Array<Function>, results: (Array | Object)): Object
Parameters
callbacks (Array<Function>) a collection of callbacks
results ((Array | Object)) unformatted results of pixel rowId information
Returns
Object: An object with the pixel results formatted for display

sessionId

Get or set the session ID used by the server to serve the correct data. This is typically set by connect and should not be set manually.

sessionId(sessionId: Number): (Number | MapdCon)
Parameters
sessionId (Number) The session ID of the current connection
Returns
(Number | MapdCon): The session ID or the MapdCon itself
Example

Get the session id:

var sessionID = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect()
  .sessionId();
// sessionID === 3145846410

Set the session id:

var con = new MapdCon().connect().sessionId(3415846410);
// NOTE: It is generally unsafe to set the session id manually.

host

Get or set the connection server hostname. This is is typically the first method called after instantiating a new MapdCon.

host(host: String): (String | MapdCon)
Parameters
host (String) The hostname address
Returns
(String | MapdCon): The hostname or the MapdCon itself
Example

Set the hostname:

var con = new MapdCon().host('localhost');

Get the hostname:

var host = con.host();
// host === 'localhost'

port

Get or set the connection port.

port(port: String): (String | MapdCon)
Parameters
port (String) The port to connect on
Returns
(String | MapdCon): The port or the MapdCon itself
Example

Set the port:

var con = new MapdCon().port('8080');

Get the port:

var port = con.port();
// port === '8080'

user

Get or set the username to authenticate with.

user(user: String): (String | MapdCon)
Parameters
user (String) The username to authenticate with
Returns
(String | MapdCon): The username or the MapdCon itself
Example

Set the username:

var con = new MapdCon().user('foo');

Get the username:

var username = con.user();
// user === 'foo'

password

Get or set the user's password to authenticate with.

password(password: String): (String | MapdCon)
Parameters
password (String) The password to authenticate with
Returns
(String | MapdCon): The password or the MapdCon itself
Example

Set the password:

var con = new MapdCon().password('bar');

Get the username:

var password = con.password();
// password === 'bar'

dbName

Get or set the name of the database to connect to.

dbName(dbName: String): (String | MapdCon)
Parameters
dbName (String) The database to connect to
Returns
(String | MapdCon): The name of the database or the MapdCon itself
Example

Set the database name:

var con = new MapdCon().dbName('myDatabase');

Get the database name:

var dbName = con.dbName();
// dbName === 'myDatabase'

logging

Whether the raw queries strings will be logged to the console. Used primarily for debugging and defaults to false.

logging(logging: Boolean): (Boolean | MapdCon)
Parameters
logging (Boolean) Set to true to enable logging
Returns
(Boolean | MapdCon): The current logging flag or MapdCon itself
Example

Set logging to true:

var con = new MapdCon().logging(true);

Get the logging flag:

var isLogging = con.logging();
// isLogging === true

platform

The name of the platform.

platform(platform: String): (String | MapdCon)
Parameters
platform (String) The platform, default is "mapd"
Returns
(String | MapdCon): The platform or the MapdCon itself
Example

Set the platform name:

var con = new MapdCon().platform('myPlatform');

Get the platform name:

var platform = con.platform();
// platform === 'myPlatform'

numConnections

Get the number of connections that are currently open.

numConnections(): Number
Returns
Number: number of open connections
Example

Get the number of connections:

var con = new MapdCon()
  .host('localhost')
  .port('8080')
  .dbName('myDatabase')
  .user('foo')
  .password('bar')
  .connect();

var numConnections = con.numConnections();
// numConnections === 1

protocol

The protocol to use for requests.

protocol(protocol: String): (String | MapdCon)
Parameters
protocol (String) http or https
Returns
(String | MapdCon): protocol or MapdCon itself
Example

Set the protocol:

var con = new MapdCon().protocol('http');

Get the protocol:

var protocol = con.protocol();
// protocol === 'http'

getEndpoints

Generates a list of endpoints from the connection params.

getEndpoints(): Array<String>
Returns
Array<String>: list of endpoints
Example

Get the endpoints:

var con = new MapdCon().protocol('http').host('localhost').port('8000');
var endpoints = con.getEndpoints();
// endpoints === [ 'http://localhost:8000' ]

processColumnarResults

Because it is inefficient for the server to return a row-based data structure, it is better to process the column-based results into a row-based format after the fact.

processColumnarResults(data: TRowSet, eliminateNullRows: Boolean, dataEnum: Object): Object
Parameters
data (TRowSet) The column-based data returned from a query
eliminateNullRows (Boolean) A flag that allows removal of null rows from results
dataEnum (Object) A list of types created from when executing #invertDatumTypes
Returns
Object: processedResults The formatted results of the query

processQueryResults

Decides how to process raw results once they come back from the server.

processQueryResults(logging: Boolean, updateQueryTimes: Function, options: Object, the: Array<Function>, result: Object): Object
Parameters
logging (Boolean) if enabled, will show how long the query took to execute in console
updateQueryTimes (Function) A function that updates internal query times on connector
options (Object) A list of options for processing the results
Name Description
options.isImage Boolean Set to true when querying for backend rendered images
options.eliminateNullRows Boolean Removes null rows
options.query String The SQL query string used only for logging
options.queryId Number The ID of the query
options.conId Number The unique connector identification
options.estimatedQueryTime String The estimate of the query time
the (Array<Function>) same callback coming from #query
result (Object) The query result used to decide whether to process as column or row results.
Returns
Object: null if image with callbacks, result if image with callbacks, otherwise formatted results

processRowResults

It should be avoided to query for row-based results from the server, howerver it can still be done. In this case, still process them into the same format as (@link processColumnarResults} to keep the output consistent.

processRowResults(data: TRowSet, eliminateNullRows: Boolean, datumEnum: Object): Object
Parameters
data (TRowSet) The row-based data returned from a query
eliminateNullRows (Boolean) A flag that allows removal of null rows from results
datumEnum (Object) A list of types created from when executing #invertDatumTypes
Returns
Object: processedResults

TDatumVal

The value of an individual cell in a table.

TDatumVal

Type: TDatumVal

Properties
arr_val (Array)
int_val (Number)
real_val (Number)
str_val (String)

TTableType

The types of tables that uploaded through the importer TTableType.

TTableType

Type: TTableType

Properties
DELIMITED (Number) : =0
POLYGON (Number) : =1

TDetectResult

Contains the result from calling detectColumnTypes.

TDetectResult

Type: TDetectResult

Properties
copy_params (TCopyParams)
row_set (TRowSet)

TTypeInfo

The information about a particular field in a given table.

TTypeInfo

Type: TTypeInfo

Properties
encoding (Number)
is_array (Boolean)
nullable (Boolean)
type (Number)

TDatumType

The valid types for database field values.

TDatumType

Type: Object

Properties
SMALLINT (Number) : =0
INT (Number) : =1
BIGINT (Number) : =2
FLOAT (Number) : =3
DECIMAL (Number) : =4
DOUBLE (Number) : =5
STR (Number) : =6
TIME (Number) : =7
TIMESTAMP (Number) : =8
DATE (Number) : =9
BOOL (Number) : =10

TImportStatus

The value of an individual cell in a table.

TImportStatus

Type: TImportStatus

Properties
elapsed (Number)
rows_completed (Number)
rows_estimated (Number)

TFrontendView

The data stored for a given dashboard.

TFrontendView

Type: TFrontendView

Properties
image_hash (String) : The lookup hash for the dashboard thumbnail image
update_time (String) : The timestamp from the last saved update
view_name (String) : The name of the dashboard or the shortened share link hash
view_state (String) : The base64-encoded string containing all the details about the current state of the dashboard

TDatum

The value and state of an individual data cell in a table.

TDatum

Type: TDatum

Properties
is_null (Boolean)
val (TDatumVal)

TRow

A row of data in a table.

TRow

Type: TRow

Properties
cols (Array<TDatum>) : The array of individual data cells in a table.

TColumnType

TColumnType

Type: TColumnType

Properties
col_name (String) : The name of the table field
col_type (TTypeInfo) : The information about the field

TRowSet

Contains parsed table data.

TRowSet

Type: TRowSet

Properties
columns (Array)
is_columnar (Boolean)
row_desc (Array<TColumnType>) : A list of field names and their associated information.
rows (Array<TRow>)

TServerStatus

The permissions granted by the server.

TServerStatus

Type: TServerStatus

Properties
read_only (Boolean) : Indicates whether server accepts write operations, eg: save dashboard
rendering_enabled (Boolean) : Indicates whether the server has backend rendering enabled
version (String) : the current version

TCopyParams

The configuration needed to import a table into MapD. See detectColumnTypes for usage example.

TCopyParams

Type: TCopyParams

Properties
array_begin (String) : =null
array_delim (String) : =null
array_end (String) : =null
delimiter (String) : ="" - The character delimiter (eg: comma, [ TAB ] , or pipe)
escape (String) : =null
has_header (Boolean) : =null
line_delim (String) : =null
null_str (String) : ="" - The token used by the table to express a null value (eg: some systems use 'nil' or 'none')
quote (String) : =null
quoted (Boolean) : =true - Indicates whether the String fields should be wrapped in quotes
threads (Number) : =null