# Arquero API Reference

 Top-Level Table Verbs Op Functions Expressions Extensibility

# table.numCols() · Source

The number of columns in this table.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.numCols() // 2
``````

# table.numRows() · Source

The number of active (non-filtered) rows in this table. This number may be less than the total rows if the table has been filtered.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.numRows() // 3
``````
``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.filter(d => d.a > 2)
.numRows() // 1
``````

# table.size · Source

The number of active (non-filtered) rows in this table. This number is the same as numRows(), and may be less than the total rows if the table has been filtered.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.size // 3
``````
``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.filter(d => d.a > 2)
.size // 1
``````

# table.totalRows() · Source

The total number of rows in this table, including both filtered and unfiltered rows.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.totalRows() // 3
``````
``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.filter(d => d.a > 2)
.totalRows() // 3
``````

# table.isFiltered() · Source

Indicates if the table has a filter applied.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.isFiltered() // false
``````
``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.filter(d => d.a > 2)
.isFiltered() // true
``````

# table.isGrouped() · Source

Indicates if the table has a groupby specification.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.isGrouped() // false
``````
``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.groupby('a')
.isGrouped() // true
``````

# table.isOrdered() · Source

Indicates if the table has a row order comparator.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.isOrdered() // false
``````
``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.orderby(aq.desc('b'))
.isOrdered() // true
``````

# table.comparator() · Source

Returns the row order comparator function, if specified.

# table.groups() · Source

Returns the groupby specification, if defined. A groupby specification is an object with the following properties:

• names: Output column names for each group field.
• get: Value accessor functions for each group field.
• rows: Row indices of example table rows for each group.
• size: The total number of groups.
• keys: Per-row group indices for every row in the table.

Returns the bitset mask for filtered rows, or null if there is no filter.

# table.params() · Source

Get or set table expression parameter values. If called with no arguments, returns the current parameter values as an object. Otherwise, adds the provided parameters to this table’s parameter set and returns the table. Any prior parameters with names matching the input parameters are overridden.

Also see the `escape()` expression helper for a lightweight alternative that allows access to variables defined in an enclosing scope.

• values: A set of parameter values to add as an object of name-value pairs.

Examples

``````table.params({ hi: 5 }).filter((d, \$) => abs(d.value) < \$.hi)
``````

## Table Transformation

For a variety of additional transformations, see the Verbs API Reference.

# table.assign(…tables) · Source

Create a new table with additional columns drawn from one or more input tables. All tables must have the same numer of rows and will be reified prior to assignment. In the case of repeated column names, input table columns overwrite existing columns.

• tables: The input tables to merge.

Examples

``````const t1 = aq.table({ a: [1, 2], b: [3, 4] });
const t2 = aq.table({ c: [5, 6], b: [7, 8] });
t1.assign(t2); // { a: [1, 2], b: [7, 8], c: [5, 6] }
``````

# table.transform(…transforms) · Source

Apply a sequence of transformations to this table. The output of each transform is passed as input to the next transform, and the output of the last transform is then returned. This method provides a lightweight mechanism for applying custom transformations to a table.

• transforms: Transformation functions to apply to the table in sequence. Each function should take a single table as input and return a table as output.

Examples

``````aq.table({ a: [1, 2], b: [3, 4] })
.transform(
table => table.filter(d => d.b > 3),
table => table.select('a')
) // { a: [2] }
``````

## Table Columns

# table.column(name) · Source

Get the column instance with the given name, or `undefined` if does not exist. The returned column object provides a lightweight abstraction over the column storage (such as a backing array), providing a length property and get(row) method.

A column instance may be used across multiple tables and so does not track a table’s filter or orderby critera. To access filtered or ordered values, use the table get, getter, or columnArray methods.

• name: The column name.

Examples

``````const dt = aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
dt.column('b').get(1) // 5
``````

# table.columnAt(index) · Source

Get the column instance at the given index position, or `undefined` if does not exist. The returned column object provides a lightweight abstraction over the column storage (such as a backing array), providing a length property and get(row) method.

• index: The zero-based column index.

Examples

``````const dt = aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
dt.columnAt(1).get(1) // 5
``````

# table.columnArray(name[, constructor]) · Source

This method is a deprecated alias for the table array() method. Please use array() instead.

Get an array of values contained in the column with the given name. Unlike direct access through the table column method, the array returned by this method respects any table filter or orderby criteria. By default, a standard Array is returned; use the constructor argument to specify a typed array.

• name: The column name.
• constructor: An optional array constructor (default `Array`) to use to instantiate the output array. Note that errors or truncated values may occur when assigning to a typed array with an incompatible type.

# table.columnIndex(name) · Source

The column index for the given name, or `-1` if the name is not found.

• name: The column name.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.columnIndex('b'); // 1
``````

# table.columnName(index) · Source

The column name at the given index, or `undefined` if the index is out of range.

• index: The column index.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.columnName(1); // 'b'
``````

# table.columnNames([filter]) · Source

Returns an array of table column names, optionally filtered.

• filter: An optional filter callback function. If unspecified, all column names are returned. If filter is provided, it will be invoked for each column name and only those for which the callback returns a truthy value will be kept. The filter callback function is called with the following arguments:
• name: The column name.
• index: The column index.
• array: The backing array of names.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.columnNames(); // [ 'a', 'b' ]
``````

## Table Values

# table.array(name[, constructor]) · Source

Get an array of values contained in the column with the given name. Unlike direct access through the table column method, the array returned by this method respects any table filter or orderby criteria. By default, a standard Array is returned; use the constructor argument to specify a typed array.

• name: The column name.
• constructor: An optional array constructor (default `Array`) to use to instantiate the output array. Note that errors or truncated values may occur when assigning to a typed array with an incompatible type.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.array('b'); // [ 4, 5, 6 ]
``````
``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.filter(d => d.a > 1)
.array('b'); // [ 5, 6 ]
``````
``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.array('b', Int32Array); // Int32Array.of(4, 5, 6)
``````

# table.values(name) · Source

Returns an iterator over values in the column with the given name. The iterator returned by this method respects any table filter or orderby criteria.

• name: The column name.

Examples

``````for (const value of table.values('colA')) {
// do something with ordered values from column A
}
``````
``````// slightly less efficient version of table.columnArray('colA')
const colValues = Array.from(table.values('colA'));
``````

# table.data() · Source

Returns the internal table storage data structure.

# table.get(name[, row]) · Source

Get the value for the given column and row. Row indices are relative to any filtering and ordering criteria, not the internal data layout.

• name: The column name.
• row: The row index (default `0`), relative to any filtering or ordering criteria.

Examples

``````const dt = aq.table({ a: [1, 2, 3], b: [4, 5, 6] });
dt.get('a', 0) // 1
dt.get('a', 2) // 3
``````
``````const dt = aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.orderby(aq.desc('b'));
dt.get('a', 0) // 3
dt.get('a', 2) // 1
``````

# table.getter(name) · Source

Returns an accessor (“getter”) function for a column. The returned function takes a row index as its single argument and returns the corresponding column value. Row indices are relative to any filtering and ordering criteria, not the internal data layout.

• name: The column name.

Examples

``````const get = aq.table({ a: [1, 2, 3], b: [4, 5, 6] }).getter('a');
get(0) // 1
get(2) // 3
``````
``````const dt = aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.orderby(aq.desc('b'))
.getter('a');
get(0) // 3
get(2) // 1
``````

# table.indices([order]) · Source

Returns an array of indices for all rows passing the table filter.

• order: A boolean flag (default `true`) indicating if the returned indices should be sorted if this table is ordered. If `false`, the returned indices may or may not be sorted.

# table.partitions([order]) · Source

Returns an array of indices for each group in the table. If the table is not grouped, the result is the same as indices, but wrapped within an array. Otherwise returns an array of row index arrays, one per group. The indices will be filtered if the table has been filtered.

• order: A boolean flag (default `true`) indicating if the returned indices should be sorted if this table is ordered. If `false`, the returned indices may or may not be sorted.

# table.scan(callback[, order]) · Source

Perform a table scan, invoking the provided callback function for each row of the table. If this table is filtered, only rows passing the filter are visited.

• callback: Function invoked for each row of the table. The callback is invoked with the following arguments:
• row: The table row index.
• data: The backing table data store.
• stop: A function to stop the scan early. The callback can invoke stop() to prevent future scan calls.
• order: A boolean flag (default `false`), indicating if the table should be scanned in the order determined by orderby. This argument has no effect if the table is unordered.

## Table Output

# table.objects([options]) · Source

Returns an array of objects representing table rows. A new set of objects will be created, copying the backing table data.

• options: Options for row generation:
• limit: The maximum number of objects to create (default `Infinity`).
• offset: The row offset indicating how many initial rows to skip (default `0`).
• columns: An ordered set of columns to include. The input may consist of: column name strings, column integer indices, objects with current column names as keys and new column names as values (for renaming), or a selection helper function such as all, not, or range).
• grouped: The export format for groups of rows. This option only applies to tables with groups set with the groupby verb. The default (`false`) is to ignore groups, returning a flat array of objects. The valid values are `true` or `'map'` (for Map instances), `'object'` (for standard Objects), or `'entries'` (for arrays in the style of Object.entries). For the `'object'` format, groupby keys are coerced to strings to use as object property names; note that this can lead to undesirable behavior if the groupby key values do not coerce to unique strings. The `'map'` and `'entries'` options preserve the groupby key values.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] }).objects()
// [ { a: 1, b: 4 }, { a: 2, b: 5 }, { a: 3, b: 6 } ]
``````
``````aq.table({ k: ['a', 'b', 'a'], v: [1, 2, 3] })
.groupby('k')
.objects({ grouped: true })
// new Map([
//   [ 'a', [ { k: 'a', v: 1 }, { k: 'a', v: 3 } ] ],
//   [ 'b', [ { k: 'b', v: 2 } ] ]
// ])
``````

# table.object([row]) · Source

Returns an object representing a single table row. The row index is relative to any filtering and ordering criteria, not the internal data layout. If the row index is not specified, the first row in the table (index `0`) is returned.

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] }).object(1) // { a: 2, b : 5}
``````
``````const { min, max } = aq.table({ v: [1, 2, 3] })
.rollup({ min: op.min('v'), max: op.max('v') })
.object(); // { min: 1, max: 3 }
``````

# table[Symbol.iterator]() · Source

Returns an iterator over generated row objects. Similar to the objects method, this method generates new row object instances; however, rather than returning an array, this method provides an iterator over row objects for each non-filtered row in the table.

Examples

``````for (const rowObject of table) {
// do something with row object
}
``````
``````// slightly less efficient version of table.objects()
const objects = [...table];
``````

# table.print([options]) · Source

Print the contents of this table using the `console.table()` method.

• options: Options for printing. If number-valued, specifies the row limit (equivalent to `{ limit: value }`).
• limit: The maximum number of rows to print (default `10`).
• offset: The row offset indicating how many initial rows to skip (default `0`).
• columns: An ordered set of columns to print. The input may consist of: column name strings, column integer indices, objects with current column names as keys and new column names as values (for renaming), or a selection helper function such as all, not, or range).

Examples

``````aq.table({ a: [1, 2, 3], b: [4, 5, 6] }).print()
// ┌─────────┬───┬───┐
// │ (index) │ a │ b │
// ├─────────┼───┼───┤
// │    0    │ 1 │ 4 │
// │    1    │ 2 │ 5 │
// │    2    │ 3 │ 6 │
// └─────────┴───┴───┘
``````

# table.toHTML([options]) · Source

Format this table as an HTML table string.

• options: A formatting options object:
• limit: The maximum number of rows to print (default `100`).
• offset: The row offset indicating how many initial rows to skip (default `0`).
• columns: Ordered list of column names to print. If function-valued, the function should accept a table as input and return an array of column name strings. Otherwise, should be an array of name strings.
• align: Object of column alignment options. The object keys should be column names. The object values should be aligment strings, one of `'l'` (left), `'c'` (center), or `'r'` (right). If specified, these override any automatically inferred options.
• format: Object of column format options. If specified, these override any automatically inferred options. The object keys should be column names. The object values should either be formatting functions or objects with any of the following properties:
• utc: A boolean flag indicating if UTC date formatting should be used rather than the local time zone.
• digits: Number of fractional digits to include for numbers.
• maxdigits: The maximum number of fractional digits to include when inferring a number format (default `6`). This option is passed to the format inference method and is ignored when explicit format options are specified.
• null: Optional format function for `null` and `undefined` values. If specified, this function be invoked with the `null` or `undefined` value as the sole input argument. The return value is then used as the HTML output for the input value.
• style: CSS styles to include in HTML output. The object keys can be HTML table tag names: `'table'`, `'thead'`, `'tbody'`, `'tr'`, `'th'`, or `'td'`. The object values should be strings of valid CSS style directives (such as `"font-weight: bold;"`) or functions that take a column name and row as input and return a CSS string.

Examples

``````// serialize a table as HTML-formatted text
aq.table({ a: [1, 2, 3], b: [4, 5, 6] }).toHTML()
``````

# table.toMarkdown([options]) · Source

Format this table as a GitHub-Flavored Markdown table string.

• options: A formatting options object:
• limit: The maximum number of rows to print (default `100`).
• offset: The row offset indicating how many initial rows to skip (default `0`).
• columns: Ordered list of column names to print. If function-valued, the function should accept a table as input and return an array of column name strings. Otherwise, should be an array of name strings.
• align: Object of column alignment options. The object keys should be column names. The object values should be aligment strings, one of `'l'` (left), `'c'` (center), or `'r'` (right). If specified, these override any automatically inferred options.
• format: Object of column format options. If specified, these override any automatically inferred options. The object keys should be column names. The object values should either be formatting functions or objects with any of the following properties:
• utc: A boolean flag indicating if UTC date formatting should be used rather than the local time zone.
• digits: Number of fractional digits to include for numbers.
• maxdigits: The maximum number of fractional digits to include when inferring a number format (default `6`). This option is passed to the format inference method and is ignored when explicit format options are specified.

Examples

``````// serialize a table as Markdown-formatted text
aq.table({ a: [1, 2, 3], b: [4, 5, 6] }).toMarkdown()
// '|a|b|\n|-:|-:|\n|1|4|\n|2|5|\n|3|6|\n'
``````

# table.toArrow([options]) · Source

Format this table as an Apache Arrow table instance. This method will throw an error if type inference fails or if the generated columns have differing lengths.

• options: Options for Arrow encoding.
• columns: Ordered list of column names to include. If function-valued, the function should accept this table as a single argument and return an array of column name strings.
• limit: The maximum number of rows to include (default `Infinity`).
• offset: The row offset indicating how many initial rows to skip (default `0`).
• types: An optional object indicating the Arrow data type to use for named columns. If specified, the input should be an object with column names for keys and Arrow data types for values. If a column’s data type is not explicitly provided, type inference will be performed.

Type values can either be instantiated Arrow DataType instances (for example, `new Float64()`,`new DateMilliseconds()`, etc.) or type enum codes (`Type.Float64`, `Type.Date`, `Type.Dictionary`). High-level types map to specific data type instances as follows:

• `Type.Date``new DateMilliseconds()`
• `Type.Dictionary``new Dictionary(new Utf8(), new Int32())`
• `Type.Float``new Float64()`
• `Type.Int``new Int32()`
• `Type.Interval``new IntervalYearMonth()`
• `Type.Time``new TimeMillisecond()`

Types that require additional parameters (including `List`, `Struct`, and `Timestamp`) can not be specified using type codes. Instead, use data type constructors from apache-arrow, such as `new List(new Int32())`.

Examples

Encode Arrow data from an input Arquero table:

``````import { table } from 'arquero';
import { Type } from 'apache-arrow';

// create Arquero table
const dt = table({
x: [1, 2, 3, 4, 5],
y: [3.4, 1.6, 5.4, 7.1, 2.9]
});

// encode as an Arrow table (infer data types)
// here, infers Uint8 for 'x' and Float64 for 'y'
const at1 = dt.toArrow();

// encode into Arrow table (set explicit data types)
const at2 = dt.toArrow({
types: {
x: Type.Uint16,
y: Type.Float32
}
});
``````

# table.toArrowBuffer([options]) · Source

Format this table as binary data in the Apache Arrow IPC format. The binary data may be saved to disk or passed between processes or tools. For example, when using Web Workers, the output of this method can be passed directly between threads (no data copy) as a Transferable object. Additionally, Arrow binary data can be loaded in other language environments such as Python or R.

This method will throw an error if type inference fails or if the generated columns have differing lengths. This method is a shorthand for `table.toArrow().serialize()`.

• options: Options for Arrow encoding, same as toArrow.

Examples

Encode Arrow data from an input Arquero table:

``````import { table } from 'arquero';

const dt = table({
x: [1, 2, 3, 4, 5],
y: [3.4, 1.6, 5.4, 7.1, 2.9]
});

// encode table as a transferable Arrow byte buffer
// here, infers Uint8 for 'x' and Float64 for 'y'
const bytes = dt.toArrowBuffer();
``````

# table.toCSV([options]) · Source

Format this table as a comma-separated values (CSV) string. Other delimiters, such as tabs or pipes (‘|’), can be specified using the options argument.

• options: A formatting options object:
• delimiter: The delimiter between values (default `","`).
• limit: The maximum number of rows to print (default `Infinity`).
• offset: The row offset indicating how many initial rows to skip (default `0`).
• columns: Ordered list of column names to include. If function-valued, the function should accept a table as input and return an array of column name strings. Otherwise, should be an array of name strings.
• format: Object of column format options. The object keys should be column names. The object values should be formatting functions that transform column values prior to output. If specified, a formatting function overrides any automatically inferred options.

Examples

``````// serialize a table as CSV-formatted text
aq.table({ a: [1, 2, 3], b: [4, 5, 6] }).toCSV()
// 'a,b\n1,4\n2,5\n3,6'
``````

# table.toJSON([options]) · Source

Format this table as a JavaScript Object Notation (JSON) string compatible with the fromJSON method.

• options: A formatting options object:
• limit: The maximum number of rows to print (default `Infinity`).
• offset: The row offset indicating how many initial rows to skip (default `0`).
• schema: Boolean flag (default `true`) indicating if table schema metadata should be included in the JSON output. If `false`, only the data payload is included.
• columns: Ordered list of column names to print. If function-valued, the function should accept a table as input and return an array of column name strings. Otherwise, should be an array of name strings.
• format: Object of column format options. The object keys should be column names. The object values should be formatting functions that transform column values prior to output. If specified, a formatting function overrides any automatically inferred options.

Examples

``````// serialize a table as a JSON string with schema metadata
aq.table({ a: [1, 2, 3], b: [4, 5, 6] }).toJSON()
// '{"schema":{"fields":[{"name":"a"},{"name":"b"}]},"data":{"a":[1,2,3],"b":[4,5,6]}}'
``````
``````// serialize a table as a JSON string without schema metadata
aq.table({ a: [1, 2, 3], b: [4, 5, 6] }).toJSON({ schema: false })
// '{"a":[1,2,3],"b":[4,5,6]}'
``````