fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Identifiers, Keys, Joins, and Data Grain

Install and import#

bash
npm install fintech-algorithms
ts
import { identifiersKeysJoinsAndDataGrain } from "fintech-algorithms/foundations/data-variables-samples-and-measurement/identifiers-keys-joins-and-data-grain";

Signature#

identifiersKeysJoinsAndDataGrain(input)

Checks whether a proposed set of key columns really identifies one row each, which is what makes a table safe to join.

Parameters#

NameTypeNotes
inputD00InputA plain object. Every F03 topic first reads rows, which must be a non-empty array of row objects, and derives the sorted union of every key seen across them before any per-topic branch runs. This topic then reads keyColumns, an optional array of column names forming the candidate key; it defaults to entity and timestamp.

Returns#

{ grain: string; unique: boolean; duplicateKeys: number }

grain is a label built from the key column names. duplicateKeys is the number of rows beyond the first that repeat a key combination, and unique is true exactly when that count is 0.

Errors#

  • When input is not a plain object — throws TypeError
  • When rows is missing, empty, or not an array — throws RangeError

Complexity: time O(r * c), space O(r * c).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

input
{
  "rows": [
    {
      "entity": "A",
      "timestamp": "2025-01-01T00:00:00Z",
      "value": 10,
      "rating": "low"
    },
    {
      "entity": "A",
      "timestamp": "2025-01-02T00:00:00Z",
      "value": null,
      "rating": "medium",
      "censored": true
    },
    {
      "entity": "B",
      "timestamp": "2025-01-01T00:00:00Z",
      "value": 12,
      "rating": "high"
    }
  ],
  "ordinalColumns": ["rating"],
  "populationSize": 100,
  "frameSize": 80,
  "keyColumns": ["entity", "timestamp"],
  "truncationRule": "values below 5 excluded",
  "measurements": [9.9, 10, 10.1, 10],
  "referenceValue": 10,
  "vintages": [
    {
      "availableAt": "2025-02-01T00:00:00Z",
      "value": 100
    },
    {
      "availableAt": "2025-03-01T00:00:00Z",
      "value": 102
    },
    {
      "availableAt": "2025-04-01T00:00:00Z",
      "value": 101
    }
  ],
  "asOf": "2025-03-15T00:00:00Z",
  "provenance": {
    "source": "teaching.csv",
    "owner": "Fintech Builder",
    "license": "CC-BY-4.0",
    "retrievedAt": "2026-08-10",
    "transformations": ["parse", "validate"]
  }
}

Call#

identifiersKeysJoinsAndDataGrain(input)

Returns#

object with 2 fields: grain, unique

{
  "grain": "entity × timestamp",
  "unique": true
}

Diagrams#

Identifiers, Keys, Joins, and Data Grain — article hero
Identifiers, Keys, Joins, and Data Grain — concept anatomy
Identifiers, Keys, Joins, and Data Grain — mistake contrast
Identifiers, Keys, Joins, and Data Grain — teaching map

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

  • Constraints
  • merge
  • Evidence boundary

The rest of the Data, Variables, Samples, and Measurement family#