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 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 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 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.array('colA')
const colValues = Array.from(table.values('colA'));

# table.data() · Source

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.

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 using Flechette. 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 { 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.toArrowIPC([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.

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.

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.