{"id":"join-cardinality","title":"Row multiplication, unmatched keys and uniqueness violations before a table join","description":"Takes the join keys of two tables (every row's key, or distinct keys with row counts) and computes the exact output row count of an inner, left, right or full equi-join with SQL NULL semantics, the observed cardinality (one-to-one, one-to-many, many-to-one, many-to-many), the keys that multiply rows the most, unmatched keys on each side and the first duplicate row when a side was assumed unique. It also flags keys that match only after loose coercion (7 vs \"7\", \"007\" vs 7, trailing spaces, case), which silently join nothing in a typed engine. For agents about to merge, enrich or deduplicate tables. It sees only the keys you send: it does not read data, and it cannot know whether a composite key is complete.","roi":"Catches fan-out, silent row loss and key-type mismatches before the join runs. 20,000 keys per side per $0.005 call.","audience":"developer","package":"data-contract-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/join-cardinality","path":"/api/v1/join-cardinality","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["left","right","joinType"],"properties":{"left":{"type":"object","additionalProperties":false,"properties":{"keys":{"type":"array","maxItems":20000,"items":{"description":"One row's join key: a string, number or boolean, null for SQL NULL, or an array of those for a composite key."},"description":"Join key of every row, in table order."},"counts":{"type":"array","maxItems":5000,"items":{"type":"object","additionalProperties":false,"required":["key","count"],"properties":{"key":{"description":"A join key (scalar, null, or array for composite)."},"count":{"type":"integer","minimum":1,"maximum":1000000}}},"description":"Key summary: how many rows carry each distinct key."},"nullRows":{"type":"integer","minimum":0,"maximum":1000000,"description":"With counts: rows whose key is NULL."}}},"right":{"type":"object","additionalProperties":false,"properties":{"keys":{"type":"array","maxItems":20000,"items":{"description":"One row's join key: a string, number or boolean, null for SQL NULL, or an array of those for a composite key."},"description":"Join key of every row, in table order."},"counts":{"type":"array","maxItems":5000,"items":{"type":"object","additionalProperties":false,"required":["key","count"],"properties":{"key":{"description":"A join key (scalar, null, or array for composite)."},"count":{"type":"integer","minimum":1,"maximum":1000000}}},"description":"Key summary: how many rows carry each distinct key."},"nullRows":{"type":"integer","minimum":0,"maximum":1000000,"description":"With counts: rows whose key is NULL."}}},"joinType":{"type":"string","enum":["inner","left","right","full"]},"expect":{"type":"object","additionalProperties":false,"properties":{"leftUnique":{"type":"boolean","description":"Left keys (non-NULL) must be distinct."},"rightUnique":{"type":"boolean","description":"Right keys (non-NULL) must be distinct."},"everyLeftMatched":{"type":"boolean"},"everyRightMatched":{"type":"boolean"},"noRowMultiplication":{"type":"boolean","description":"The output must not have more rows than the preserved side."},"maxOutputRows":{"type":"integer","minimum":0,"maximum":9000000000000000}}},"normalize":{"type":"object","additionalProperties":false,"properties":{"trim":{"type":"boolean"},"caseFold":{"type":"boolean"}},"description":"Normalization your pipeline applies to string keys before joining."}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"left":{"type":"object","properties":{"rows":{"type":"integer"},"distinctKeys":{"type":"integer"},"nullKeyRows":{"type":"integer"},"maxMultiplicity":{"type":"integer"},"unique":{"type":"boolean"}}},"right":{"type":"object","properties":{"rows":{"type":"integer"},"distinctKeys":{"type":"integer"},"nullKeyRows":{"type":"integer"},"maxMultiplicity":{"type":"integer"},"unique":{"type":"boolean"}}},"observedCardinality":{"type":"string","enum":["one-to-one","one-to-many","many-to-one","many-to-many"]},"outputRows":{"type":"object","properties":{"inner":{"type":"integer"},"left":{"type":"integer"},"right":{"type":"integer"},"full":{"type":"integer"},"selected":{"type":"integer"}}},"multiplicationFactor":{"anyOf":[{"type":"number","description":"Selected join's output rows divided by the preserved side's rows (left for inner/left/full, right for right)."},{"type":"null"}]},"unmatched":{"type":"object","properties":{"leftKeys":{"type":"integer"},"rightKeys":{"type":"integer"},"leftRows":{"type":"integer"},"rightRows":{"type":"integer"},"leftSample":{"type":"array","items":{"description":"Key"}},"rightSample":{"type":"array","items":{"description":"Key"}}}},"fanOut":{"type":"array","items":{"type":"object","properties":{"key":{"description":"Join key"},"leftRows":{"type":"integer"},"rightRows":{"type":"integer"},"outputRows":{"type":"integer"}}}},"coercionHazards":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"left":{"description":"Left key"},"right":{"description":"Right key"}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"left":{"type":"object","properties":{"rows":{"type":"integer"},"distinctKeys":{"type":"integer"},"nullKeyRows":{"type":"integer"},"maxMultiplicity":{"type":"integer"},"unique":{"type":"boolean"}}},"right":{"type":"object","properties":{"rows":{"type":"integer"},"distinctKeys":{"type":"integer"},"nullKeyRows":{"type":"integer"},"maxMultiplicity":{"type":"integer"},"unique":{"type":"boolean"}}},"observedCardinality":{"type":"string","enum":["one-to-one","one-to-many","many-to-one","many-to-many"]},"outputRows":{"type":"object","properties":{"inner":{"type":"integer"},"left":{"type":"integer"},"right":{"type":"integer"},"full":{"type":"integer"},"selected":{"type":"integer"}}},"multiplicationFactor":{"anyOf":[{"type":"number","description":"Selected join's output rows divided by the preserved side's rows (left for inner/left/full, right for right)."},{"type":"null"}]},"unmatched":{"type":"object","properties":{"leftKeys":{"type":"integer"},"rightKeys":{"type":"integer"},"leftRows":{"type":"integer"},"rightRows":{"type":"integer"},"leftSample":{"type":"array","items":{"description":"Key"}},"rightSample":{"type":"array","items":{"description":"Key"}}}},"fanOut":{"type":"array","items":{"type":"object","properties":{"key":{"description":"Join key"},"leftRows":{"type":"integer"},"rightRows":{"type":"integer"},"outputRows":{"type":"integer"}}}},"coercionHazards":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"left":{"description":"Left key"},"right":{"description":"Right key"}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"left":{"keys":[1,2,3,3,null,"007"]},"right":{"keys":[1,3,3,4,"7"," 1"]},"joinType":"left","expect":{"rightUnique":true,"noRowMultiplication":true}},"openapiOperation":{"operationId":"join_cardinality","summary":"Row multiplication, unmatched keys and uniqueness violations before a table join","description":"Takes the join keys of two tables (every row's key, or distinct keys with row counts) and computes the exact output row count of an inner, left, right or full equi-join with SQL NULL semantics, the observed cardinality (one-to-one, one-to-many, many-to-one, many-to-many), the keys that multiply rows the most, unmatched keys on each side and the first duplicate row when a side was assumed unique. It also flags keys that match only after loose coercion (7 vs \"7\", \"007\" vs 7, trailing spaces, case), which silently join nothing in a typed engine. For agents about to merge, enrich or deduplicate tables. It sees only the keys you send: it does not read data, and it cannot know whether a composite key is complete.\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"developer","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/join-cardinality","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["left","right","joinType"],"properties":{"left":{"type":"object","additionalProperties":false,"properties":{"keys":{"type":"array","maxItems":20000,"items":{"description":"One row's join key: a string, number or boolean, null for SQL NULL, or an array of those for a composite key."},"description":"Join key of every row, in table order."},"counts":{"type":"array","maxItems":5000,"items":{"type":"object","additionalProperties":false,"required":["key","count"],"properties":{"key":{"description":"A join key (scalar, null, or array for composite)."},"count":{"type":"integer","minimum":1,"maximum":1000000}}},"description":"Key summary: how many rows carry each distinct key."},"nullRows":{"type":"integer","minimum":0,"maximum":1000000,"description":"With counts: rows whose key is NULL."}}},"right":{"type":"object","additionalProperties":false,"properties":{"keys":{"type":"array","maxItems":20000,"items":{"description":"One row's join key: a string, number or boolean, null for SQL NULL, or an array of those for a composite key."},"description":"Join key of every row, in table order."},"counts":{"type":"array","maxItems":5000,"items":{"type":"object","additionalProperties":false,"required":["key","count"],"properties":{"key":{"description":"A join key (scalar, null, or array for composite)."},"count":{"type":"integer","minimum":1,"maximum":1000000}}},"description":"Key summary: how many rows carry each distinct key."},"nullRows":{"type":"integer","minimum":0,"maximum":1000000,"description":"With counts: rows whose key is NULL."}}},"joinType":{"type":"string","enum":["inner","left","right","full"]},"expect":{"type":"object","additionalProperties":false,"properties":{"leftUnique":{"type":"boolean","description":"Left keys (non-NULL) must be distinct."},"rightUnique":{"type":"boolean","description":"Right keys (non-NULL) must be distinct."},"everyLeftMatched":{"type":"boolean"},"everyRightMatched":{"type":"boolean"},"noRowMultiplication":{"type":"boolean","description":"The output must not have more rows than the preserved side."},"maxOutputRows":{"type":"integer","minimum":0,"maximum":9000000000000000}}},"normalize":{"type":"object","additionalProperties":false,"properties":{"trim":{"type":"boolean"},"caseFold":{"type":"boolean"}},"description":"Normalization your pipeline applies to string keys before joining."}}},"example":{"left":{"keys":[1,2,3,3,null,"007"]},"right":{"keys":[1,3,3,4,"7"," 1"]},"joinType":"left","expect":{"rightUnique":true,"noRowMultiplication":true}}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"left":{"type":"object","properties":{"rows":{"type":"integer"},"distinctKeys":{"type":"integer"},"nullKeyRows":{"type":"integer"},"maxMultiplicity":{"type":"integer"},"unique":{"type":"boolean"}}},"right":{"type":"object","properties":{"rows":{"type":"integer"},"distinctKeys":{"type":"integer"},"nullKeyRows":{"type":"integer"},"maxMultiplicity":{"type":"integer"},"unique":{"type":"boolean"}}},"observedCardinality":{"type":"string","enum":["one-to-one","one-to-many","many-to-one","many-to-many"]},"outputRows":{"type":"object","properties":{"inner":{"type":"integer"},"left":{"type":"integer"},"right":{"type":"integer"},"full":{"type":"integer"},"selected":{"type":"integer"}}},"multiplicationFactor":{"anyOf":[{"type":"number","description":"Selected join's output rows divided by the preserved side's rows (left for inner/left/full, right for right)."},{"type":"null"}]},"unmatched":{"type":"object","properties":{"leftKeys":{"type":"integer"},"rightKeys":{"type":"integer"},"leftRows":{"type":"integer"},"rightRows":{"type":"integer"},"leftSample":{"type":"array","items":{"description":"Key"}},"rightSample":{"type":"array","items":{"description":"Key"}}}},"fanOut":{"type":"array","items":{"type":"object","properties":{"key":{"description":"Join key"},"leftRows":{"type":"integer"},"rightRows":{"type":"integer"},"outputRows":{"type":"integer"}}}},"coercionHazards":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"left":{"description":"Left key"},"right":{"description":"Right key"}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/join-cardinality/","docsJson":"https://agents.writerslogic.com/docs/join-cardinality.json","sample":"https://agents.writerslogic.com/api/v1/samples/join-cardinality","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}