Top-Level | Table | Verbs | Op Functions | Expressions | Extensibility |
The number of columns in this table.
Examples
aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.numCols() // 2
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
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
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
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
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
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
Returns the row order comparator function, if specified.
Returns the groupby specification, if defined. A groupby specification is an object with the following properties:
Returns the bitset mask for filtered rows, or null if there is no filter.
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.
Examples
table.params({ hi: 5 }).filter((d, $) => abs(d.value) < $.hi)
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.
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.
Examples
aq.table({ a: [1, 2], b: [3, 4] })
.transform(
table => table.filter(d => d.b > 3),
table => table.select('a')
) // { a: [2] }
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 array methods.
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.
Examples
const dt = aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
dt.columnAt(1).get(1) // 5
# table.columnIndex(name) · Source
The column index for the given name, or -1
if the name is not found.
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.
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.
Examples
aq.table({ a: [1, 2, 3], b: [4, 5, 6] })
.columnNames(); // [ 'a', 'b' ]
# 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.
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)
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.
Examples
for (const value of table.values('colA')) {
// do something with ordered values from column A
}
// slightly less efficient version of table.array('colA')
const colValues = Array.from(table.values('colA'));
Returns the internal table storage data structure: an object with column names for keys and column arrays for values. This method returns the same structure used by the Table (not a copy) and its contents should not be modified.
# 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.
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
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.
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.
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.
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.
data
method).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.objects([options]) · Source
Returns an array of objects representing table rows. A new set of objects will be created, copying the backing table data.
Infinity
).0
).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.
{ limit: value }
).
10
).0
).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.
100
).0
).'l'
(left), 'c'
(center), or 'r'
(right). If specified, these override any automatically inferred options.6
). This option is passed to the format inference method and is ignored when explicit format options are specified.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.'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.
100
).0
).'l'
(left), 'c'
(center), or 'r'
(right). If specified, these override any automatically inferred options.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 using Flechette. This method will throw an error if type inference fails or if the generated columns have differing lengths.
Infinity
).0
).float64()
,dateDay()
, list(int32())
etc.). If a column’s data type is not explicitly provided, type inference will be performed.false
) to extract 64-bit integer types as JavaScript BigInt
values. For Flechette tables, the default is to coerce 64-bit integers to JavaScript numbers and raise an error if the number is out of range. This option is only applied when parsing IPC binary data, otherwise the settings of the provided table instance are used.true
) to convert Arrow date and timestamp values to JavaScript Date objects. Otherwise, numeric timestamps are used. This option is only applied when parsing IPC binary data, otherwise the settings of the provided table instance are used.false
) to extract Arrow decimal-type data as BigInt values, where fractional digits are scaled to integers. Otherwise, decimals are (sometimes lossily) converted to floating-point numbers (default). This option is only applied when parsing IPC binary data, otherwise the settings of the provided table instance are used.false
) to represent Arrow Map data as JavaScript Map
values. For Flechette tables, the default is to produce an array of [key, value]
arrays. This option is only applied when parsing IPC binary data, otherwise the settings of the provided table instance are used.false
) to extract Arrow Struct values and table row objects using zero-copy proxy objects that extract data from underlying Arrow batches. The proxy objects can improve performance and reduce memory usage, but do not support property enumeration (Object.keys
, Object.values
, Object.entries
) or spreading ({ ...object }
). This option is only applied when parsing IPC binary data, otherwise the settings of the provided table instance are used.Examples
Encode Arrow data from an input Arquero table:
import { float32, uint16 } from '@uwdata/flechette';
import { table } from 'arquero';
// 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: uint16(),
y: float32()
}
});
# table.toArrowBuffer([options]) · Source
Format this table as binary data in the Apache Arrow IPC format using Flechette. 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.
'stream'
(default) or 'file'
. For more details on these formats, see the Apache Arrow format documentation.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.toArrowIPC();
# 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.
","
).true
) to specify the presence of a header row. If true
, includes a header row with column names. If false
, the header is omitted.Infinity
).0
).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.
Infinity
).0
).true
) indicating if table schema metadata should be included in the JSON output. If false
, only the data payload is included.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]}'