diff --git a/docs/api/verbs.md b/docs/api/verbs.md index 830849b..14b1c08 100644 --- a/docs/api/verbs.md +++ b/docs/api/verbs.md @@ -478,13 +478,13 @@ table.join_full(other, (a, b) => op.equal(a.keyL, b.keyR)) ```
# -table.lookup(other, on, ...values) · [Source](https://github.com/uwdata/arquero/blob/master/src/verbs/lookup.js) +table.lookup(other[, on, ...values]) · [Source](https://github.com/uwdata/arquero/blob/master/src/verbs/lookup.js) -Lookup values from a secondary table and add them as new columns. A lookup occurs upon matching key values for rows in both tables. If the secondary table has multiple rows with the same key, only the last observed instance will be considered in the lookup. Lookup is similar to [join_left](#join_left), but with a streamlined syntax and the added constraint of allowing at most one match only. +Lookup values from a secondary table (*other*) and add them as new columns. A lookup occurs upon matching key values for rows in both tables. If the secondary table has multiple rows with the same key, only the last observed instance will be considered in the lookup. Lookup is similar to [join_left](#join_left), but with a streamlined syntax and the added constraint of allowing at most one match only. * *other*: The secondary table to look up values from. -* *on*: A two-element array of lookup keys (column name strings or table expressions) for this table and the secondary table, respectively. -* *values*: The column values to add from the secondary table. Can be column name strings or objects with column names as keys and table expressions as values. +* *on*: A lookup key or two-element array of lookup keys (column name strings or table expressions) for this table and the secondary table, respectively. If a single key value is provided, it is used as the lookup key for both tables. If unspecified, all columns with matching names are compared. +* *values*: The column values to add from the secondary table. Can be column name strings or objects with column names as keys and table expressions as values. If unspecified, includes all columns from the secondary table whose names do no match any column in the primary table. *Example* diff --git a/src/table/ColumnTable.js b/src/table/ColumnTable.js index 1f4be3e..2b16a93 100644 --- a/src/table/ColumnTable.js +++ b/src/table/ColumnTable.js @@ -451,11 +451,13 @@ export class ColumnTable extends Table { * The secondary table to look up values from. * @param {import('./types.js').JoinKeys} [on] * Lookup keys (column name strings or table expressions) for this table - * and the secondary table, respectively. - * @param {...import('./types.js').ExprList} values + * and the secondary table, respectively. If unspecified, the values of + * all columns with matching names are compared. + * @param {...import('./types.js').ExprList} [values] * The column values to add from the secondary table. Can be column name * strings or objects with column names as keys and table expressions as - * values. + * values. If unspecified, includes all columns from the secondary table + * whose names do no match any column in the primary table. * @return {this} A new table with lookup values added. * @example table.lookup(other, ['key1', 'key2'], 'value1', 'value2') */ diff --git a/src/verbs/lookup.js b/src/verbs/lookup.js index 3ddf656..a540739 100644 --- a/src/verbs/lookup.js +++ b/src/verbs/lookup.js @@ -1,20 +1,24 @@ +import { not } from '../api.js'; +import { columnSet } from '../table/ColumnSet.js'; +import concat from '../util/concat.js'; +import NULL from '../util/null.js'; +import unroll from '../util/unroll.js'; import { rowLookup } from './join/lookup.js'; import { aggregateGet } from './reduce/util.js'; import { inferKeys } from './util/join-keys.js'; import parseKey from './util/parse-key.js'; import parseValues from './util/parse.js'; -import { columnSet } from '../table/ColumnSet.js'; -import NULL from '../util/null.js'; -import concat from '../util/concat.js'; -import unroll from '../util/unroll.js'; export function lookup(tableL, tableR, on, ...values) { on = inferKeys(tableL, tableR, on); + values = values.length === 0 + ? [not(tableL.columnNames())] + : values.flat(); return _lookup( tableL, tableR, [ parseKey('lookup', tableL, on[0]), parseKey('lookup', tableR, on[1]) ], - parseValues('lookup', tableR, values.flat()) + parseValues('lookup', tableR, values) ); } diff --git a/test/verbs/lookup-test.js b/test/verbs/lookup-test.js index 1b45c8d..ab25944 100644 --- a/test/verbs/lookup-test.js +++ b/test/verbs/lookup-test.js @@ -51,4 +51,51 @@ describe('lookup', () => { v: [2, 0, -2, undefined, 2] }, 'lookup data'); }); + + it('retrieves values from lookup table with implicit value rows', () => { + const right = table({ + id: [1, 2, 3], + u: ['a', 'b', 'c'], + v: [5, 3, 1] + }); + + const left = table({ + id: [1, 2, 3, 4, 1], + u: [-1, -1, -1, -1, -1] + }); + + const lt = left.lookup(right, 'id'); + + assert.equal(lt.numRows(), 5, 'num rows'); + assert.equal(lt.numCols(), 3, 'num cols'); + + tableEqual(lt, { + id: [1, 2, 3, 4, 1], + u: [-1, -1, -1, -1, -1], + v: [5, 3, 1, undefined, 5] + }, 'lookup data'); + }); + + it('retrieves values from lookup table with implicit parameters', () => { + const right = table({ + id: [1, 2, 3], + u: ['a', 'b', 'c'], + v: [5, 3, 1] + }); + + const left = table({ + id: [1, 2, 3, 4, 1] + }); + + const lt = left.lookup(right); + + assert.equal(lt.numRows(), 5, 'num rows'); + assert.equal(lt.numCols(), 3, 'num cols'); + + tableEqual(lt, { + id: [1, 2, 3, 4, 1], + u: ['a', 'b', 'c', undefined, 'a'], + v: [5, 3, 1, undefined, 5] + }, 'lookup data'); + }); });