perspective API
perspective
The main API module for @finos/perspective
.
For more information, see the Javascript user guide.
- perspective
- ~view
- new view()
- .get_config() ⇒
Promise.<object>
- .delete()
- .schema() ⇒
Promise.<Object>
- .expression_schema() ⇒
Promise.<Object>
- .column_paths() ⇒
Array.<String>
- .get_min_max(colname) ⇒
Array.<Object>
- .to_columns([options]) ⇒
Promise.<Array>
- .to_json([options]) ⇒
Promise.<Array>
- .to_csv([options]) ⇒
Promise.<string>
- .col_to_js_typed_array(column_name, options) ⇒
Promise.<TypedArray>
- .to_arrow([options]) ⇒
Promise.<ArrayBuffer>
- .num_rows() ⇒
Promise.<number>
- .num_columns() ⇒
Promise.<number>
- .get_row_expanded() ⇒
Promise.<bool>
- .expand() ⇒
Promise.<void>
- .collapse() ⇒
Promise.<void>
- .set_depth()
- .on_update(callback)
- .on_delete(callback)
- .remove_delete(callback)
- ~table
- new table()
- .get_index()
- .get_limit()
- .clear()
- .replace()
- .delete()
- .on_delete(callback)
- .remove_delete(callback)
- .size() ⇒
Promise.<number>
- .schema() ⇒
Promise.<Object>
- .validate_expressions(expressions) ⇒
Promise.<Object>
- .is_valid_filter([filter])
- .view([config]) ⇒
Promise.<view>
- .update(data)
- .remove(data)
- .columns() ⇒
Promise.<Array.<string>>
- ~view
perspective~view
Kind: inner class of perspective
- ~view
- new view()
- .get_config() ⇒
Promise.<object>
- .delete()
- .schema() ⇒
Promise.<Object>
- .expression_schema() ⇒
Promise.<Object>
- .column_paths() ⇒
Array.<String>
- .get_min_max(colname) ⇒
Array.<Object>
- .to_columns([options]) ⇒
Promise.<Array>
- .to_json([options]) ⇒
Promise.<Array>
- .to_csv([options]) ⇒
Promise.<string>
- .col_to_js_typed_array(column_name, options) ⇒
Promise.<TypedArray>
- .to_arrow([options]) ⇒
Promise.<ArrayBuffer>
- .num_rows() ⇒
Promise.<number>
- .num_columns() ⇒
Promise.<number>
- .get_row_expanded() ⇒
Promise.<bool>
- .expand() ⇒
Promise.<void>
- .collapse() ⇒
Promise.<void>
- .set_depth()
- .on_update(callback)
- .on_delete(callback)
- .remove_delete(callback)
new view()
A View object represents a specific transform (configuration or pivot, filter, sort, etc) configuration on an underlying table. A View receives all updates from the table from which it is derived, and can be serialized to JSON or trigger a callback when it is updated. View objects are immutable, and will remain in memory and actively process updates until its delete method is called.
Note This constructor is not public - Views are created by invoking the [view](#module_perspective..table+view) method.Example
// Returns a new View, pivoted in the row space by the "name" column.
await table.view({group_by: ["name"]});
view.get_config() ⇒ Promise.<object>
A copy of the config object passed to the table#view method which created this view.
Kind: instance method of view
Returns: Promise.<object>
- Shared the same key/values properties as
view
view.delete()
Delete this view and clean up all resources associated with it. View objects do not stop consuming resources or processing updates when they are garbage collected - you must call this method to reclaim these.
Kind: instance method of view
view.schema() ⇒ Promise.<Object>
The schema of this view.
A schema is an Object, the keys of which are the columns of this view, and the values are their string type names. If this view is aggregated, theses will be the aggregated types; otherwise these types will be the same as the columns in the underlying table.
Kind: instance method of view
Returns: Promise.<Object>
- A Promise of this
view's schema.
Example
// Create a view
const view = await table.view({
columns: ["a", "b"]
});
const schema = await view.schema(); // {a: "float", b: "string"}
view.expression_schema() ⇒ Promise.<Object>
The expression schema of this view, which contains only the expressions created on this view.
A schema is an Object, the keys of which are the columns of this view, and the values are their string type names. If this view is aggregated, these will be the aggregated types; otherwise these types will be the same as the columns in the underlying table.
Kind: instance method of view
Returns: Promise.<Object>
- A Promise of this
view's expression schema.
Example
// Create a view with expressions
const view = table.view({
expressions: ['"x" + "y" - 100']
});
await view.expression_schema(); // {'"x" + "y" - 100': "float"}
view.column_paths() ⇒ Array.<String>
Returns an array of strings containing the column paths of the View without any of the source columns.
A column path shows the columns that a given cell belongs to after pivots are applied.
Kind: instance method of view
Returns: Array.<String>
- an Array of Strings containing the column paths.
view.get_min_max(colname) ⇒ Array.<Object>
Calculates the [min, max] of the leaf nodes of a column colname
.
Kind: instance method of view
Returns: Array.<Object>
- A tuple of [min, max], whose types are column
and aggregate dependent.
Params
- colname
String
- A column name in thisView
.
view.to_columns([options]) ⇒ Promise.<Array>
Serializes this view to JSON data in a column-oriented format.
Kind: instance method of view
Returns: Promise.<Array>
- A Promise resolving to An array of Objects
representing the rows of this view. If this
view had a "group_by" config parameter
supplied when constructed, each row Object will have a "ROW_PATH"
key, whose value specifies this row's aggregated path. If this
view had a "split_by" config parameter
supplied, the keys of this object will be comma-prepended with their
comma-separated column paths.
Params
- [options]
Object
- An optional configuration object.serialize.- .start_row <code>number</code> - The starting row index from which to
serialize.- .end_row <code>number</code> - The ending row index from which to
serialize.- .start_col <code>number</code> - The starting column index from which to
serialize.- .end_col <code>number</code> - The ending column index from which to
underlying table be in the output (as- [.index] <code>boolean</code> <code> = false</code> - Should the index from the
"__INDEX__"
).
view.to_json([options]) ⇒ Promise.<Array>
Serializes this view to JSON data in a row-oriented format.
Kind: instance method of view
Returns: Promise.<Array>
- A Promise resolving to An array of Objects
representing the rows of this view. If this
view had a "group_by" config parameter
supplied when constructed, each row Object will have a "ROW_PATH"
key, whose value specifies this row's aggregated path. If this
view had a "split_by" config parameter
supplied, the keys of this object will be comma-prepended with their
comma-separated column paths.
Params
- [options]
Object
- An optional configuration object.serialize.- .start_row <code>number</code> - The starting row index from which to
serialize.- .end_row <code>number</code> - The ending row index from which to
serialize.- .start_col <code>number</code> - The starting column index from which to
serialize.- .end_col <code>number</code> - The ending column index from which to
view.to_csv([options]) ⇒ Promise.<string>
Serializes this view to CSV data in a standard format.
Kind: instance method of view
Returns: Promise.<string>
- A Promise resolving to a string in CSV format
representing the rows of this view. If this
view had a "group_by" config parameter
supplied when constructed, each row will have prepended those values
specified by this row's aggregated path. If this
view had a "split_by" config parameter
supplied, the keys of this object will be comma-prepended with their
comma-separated column paths.
Params
- [options]
Object
- An optional configuration object.serialize.- .start_row <code>number</code> - The starting row index from which to
serialize.- .end_row <code>number</code> - The ending row index from which to
serialize.- .start_col <code>number</code> - The starting column index from which to
serialize.- .end_col <code>number</code> - The ending column index from which to
view.col_to_js_typed_array(column_name, options) ⇒ Promise.<TypedArray>
Serializes a view column into a TypedArray.
Kind: instance method of view
Returns: Promise.<TypedArray>
- A promise resolving to a TypedArray
representing the data of the column as retrieved from the
view - all pivots, aggregates, sorts, and
filters have been applied onto the values inside the TypedArray. The
TypedArray will be constructed based on data type - integers will resolve
to Int8Array, Int16Array, or Int32Array. Floats resolve to Float32Array
or Float64Array. If the column cannot be found, or is not of an
integer/float type, the Promise returns undefined.
Params
- column_name
string
- The name of the column to serialize. - options
Object
- An optional configuration object.serialize.- .data_slice <code>\*</code> - A data slice object from which to
serialize.- .start_row <code>number</code> - The starting row index from which to
serialize.- .end_row <code>number</code> - The ending row index from which to
view.to_arrow([options]) ⇒ Promise.<ArrayBuffer>
Serializes a view to the Apache Arrow data format.
Kind: instance method of view
Returns: Promise.<ArrayBuffer>
- An ArrayBuffer
in the Apache Arrow
format containing data from the view.
Params
- [options]
Object
- An optional configuration object.serialize.- .start_row <code>number</code> - The starting row index from which to
serialize.- .end_row <code>number</code> - The ending row index from which to
serialize.- .start_col <code>number</code> - The starting column index from which to
serialize.- .end_col <code>number</code> - The ending column index from which to
view.num_rows() ⇒ Promise.<number>
The number of aggregated rows in this view. This is affected by the "group_by" configuration parameter supplied to this view's contructor.
Kind: instance method of view
Returns: Promise.<number>
- The number of aggregated rows.
view.num_columns() ⇒ Promise.<number>
The number of aggregated columns in this view. This is affected by the "split_by" configuration parameter supplied to this view's contructor.
Kind: instance method of view
Returns: Promise.<number>
- The number of aggregated columns.
view.get_row_expanded() ⇒ Promise.<bool>
Whether this row at index idx
is in an expanded or collapsed state.
Kind: instance method of view
Returns: Promise.<bool>
- Whether this row is expanded.
view.expand() ⇒ Promise.<void>
Expands the row at index idx
.
Kind: instance method of view
view.collapse() ⇒ Promise.<void>
Collapses the row at index idx
.
Kind: instance method of view
view.set_depth()
Set expansion depth
of the pivot tree.
Kind: instance method of view
view.on_update(callback)
Register a callback with this view. Whenever
the view's underlying table emits an update,
this callback will be invoked with an object containing port_id
,
indicating which port the update fired on, and optionally delta
, which
is the new data that was updated for each cell or each row.
Kind: instance method of view
Params
- callback
function
- A callback function invoked on update, which receives an object with two keys:port_id
, indicating which port the update was triggered on, anddelta
, whose value is dependent on themode
parameter:- "none" (default): `delta` is `undefined`.
- "row": `delta` is an Arrow of the updated rows.
Example
// Attach an `on_update` callback
view.on_update(updated => console.log(updated.port_id));
Example
// `on_update` with row deltas
view.on_update(updated => console.log(updated.delta), {mode: "row"});
view.on_delete(callback)
Register a callback with this view. Whenever the view is deleted, this callback will be invoked.
Kind: instance method of view
Params
- callback
function
- A callback function invoked on delete.
Example
// attach an `on_delete` callback
view.on_delete(() => console.log("Deleted!"));
view.remove_delete(callback)
Unregister a previously registered delete callback with this view.
Kind: instance method of view
Params
- callback
function
- A delete callback function to be removed
Example
// remove an `on_delete` callback
const callback = () => console.log("Deleted!")
view.remove_delete(callback);
perspective~table
Kind: inner class of perspective
- ~table
- new table()
- .get_index()
- .get_limit()
- .clear()
- .replace()
- .delete()
- .on_delete(callback)
- .remove_delete(callback)
- .size() ⇒
Promise.<number>
- .schema() ⇒
Promise.<Object>
- .validate_expressions(expressions) ⇒
Promise.<Object>
- .is_valid_filter([filter])
- .view([config]) ⇒
Promise.<view>
- .update(data)
- .remove(data)
- .columns() ⇒
Promise.<Array.<string>>
new table()
A Table object is the basic data container in Perspective. Tables are typed - they have an immutable set of column names, and a known type for each.
Note This constructor is not public - Tables are created by invoking the [table](#module_perspective..table) factory method, either on the perspective module object, or an a [module:perspective~worker](module:perspective~worker) instance.table.get_index()
Returns the user-specified index column for this table or null if an index is not set.
Kind: instance method of table
table.get_limit()
Returns the user-specified limit column for this table or null if an limit is not set.
Kind: instance method of table
table.clear()
Remove all rows in this table while preserving the schema and construction options.
Kind: instance method of table
table.replace()
Replace all rows in this table the input data.
Kind: instance method of table
table.delete()
Delete this table and clean up all resources associated with it. Table objects do not stop consuming resources or processing updates when they are garbage collected - you must call this method to reclaim these.
Kind: instance method of table
table.on_delete(callback)
Register a callback with this table. Whenever the table is deleted, this callback will be invoked.
Kind: instance method of table
Params
- callback
function
- A callback function with no parameters that will be invoked ondelete()
.
table.remove_delete(callback)
Unregister a previously registered delete callback with this table.
Kind: instance method of table
Params
- callback
function
- A delete callback function to be removed
table.size() ⇒ Promise.<number>
The number of accumulated rows in this table. This is affected by the "index" configuration parameter supplied to this view's contructor - as rows will be overwritten when they share an idnex column.
Kind: instance method of table
Returns: Promise.<number>
- The number of accumulated rows.
table.schema() ⇒ Promise.<Object>
The schema of this table. A schema is an Object whose keys are the columns of this table, and whose values are their string type names.
Kind: instance method of table
Returns: Promise.<Object>
- A Promise of this
table's schema.
table.validate_expressions(expressions) ⇒ Promise.<Object>
Given an array of expressions, return an object containing expressions
,
which map expression aliases to data types, and errors
, which
maps expression aliases to error messages. If an expression that was
passed in is not in expressions
, it is guaranteed to be in errors
.
Kind: instance method of table
Params
- expressions
Array.<String>
- An array of string expressions to be validated.
Example
const results = await table.validate_expressions([
'"Sales" + "Profit"', "invalid", "1 + 'string'"
]);
// {'"Sales" + "Profit"': "float"}
console.log(results.expression_schema);
// {
// "invalid": {column: 0, line: 0, error_message: "unknown token!"},
// "1 + 'string'": {column: 0, line: 0, error_message: "Type Error"}
// }
console.log(results.errors);
table.is_valid_filter([filter])
Validates a filter configuration, i.e. that the value to filter by is not null or undefined.
Kind: instance method of table
Params
- [filter]
Array.<string>
- a filter configuration to test.
table.view([config]) ⇒ Promise.<view>
Create a new view from this table with a specified configuration. For a better understanding of the View configuration options, see the Documentation.
Kind: instance method of table
Returns: Promise.<view>
- A Promise that resolves to a new
view object for the supplied configuration,
bound to this table.
Params
- [config]
Object
- The configuration object for this view.use as Group By.- [.group_by] <code>Array.<string></code> - An array of column names to
use as Split By.- [.split_by] <code>Array.<string></code> - An array of column names to
output columns. If none are provided, all columns are output.- [.columns] <code>Array.<Object></code> - An array of column names for the
column names, and their respective values are the aggregates calculations to use when this view has- [.aggregates] <code>Object</code> - An object, the keys of which are
group_by
. A column provided toconfig.columns
without an aggregate in this object, will use the default aggregate calculation for its type.configurations to apply. A filter configuration is an array of 3 elements: A column name, a supported filter comparison string (e.g. '===', '>'), and a value to compare.- [.filter] <code>Array.<Array.<string>></code> - An Array of Filter
apply. A sort configuration is an array of 2 elements: A column name, and a sort direction, which are: "none", "asc", "desc", "col asc", "col desc", "asc abs", "desc abs", "col asc abs", "col desc abs".- [.sort] <code>Array.<string></code> - An Array of Sort configurations to
Example
const view = await table.view({
group_by: ["region"],
columns: ["region"],
aggregates: {"region": "dominant"},
filter: [["client", "contains", "fred"]],
sort: [["value", "asc"]]
});
table.update(data)
Updates the rows of a table. Updated rows are pushed down to any derived view objects.
Kind: instance method of table
See: table
Params
- data
Object.<string, Array>
|Array.<Object>
|string
- The input data for this table. tables are immutable after creation, so this method cannot be called with a schema.
Otherwise, the supported input types are the same as the table constructor.
table.remove(data)
Removes the rows of a table. Removed rows are pushed down to any derived view objects.
Kind: instance method of table
See: table
Params
- data
Array.<Object>
- An array of primary keys to remove.
table.columns() ⇒ Promise.<Array.<string>>
The column names of this table.
Kind: instance method of table
Returns: Promise.<Array.<string>>
- An array of column names for this
table.