arquero

Arquero API Reference

Top-Level Table Verbs Op Functions Expressions Extensibility


Table Metadata

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

# table.mask() · Source

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.

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.

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


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.

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

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

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.

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.

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.

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.

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

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


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.

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.

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.

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.

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.

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().

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.

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.

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]}'
This site is open source. Improve this page.