Mode 3 — Compatibility check

Use when the user asks whether a Cassandra schema or workload will run on Amazon Keyspaces, without wanting a cost estimate. For combined pricing + compatibility, run Mode 2 instead — it auto-populates the compatibility block.

Inputs

At least one of:

--schema <path.cql> — CQL DDL (DESCRIBE SCHEMA output or hand-written).
--prepared <path.ndjson> — system.prepared_statements export as NDJSON (one JSON object per line).

Both may be supplied together. CQL may also be piped on stdin when --prepared is absent.

Command

cd scripts

# Schema file
npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  --schema /tmp/schema.cql | tee /tmp/keyspaces-compat.json

# Prepared statements file
npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  --prepared /tmp/prepared_statements.ndjson | tee /tmp/keyspaces-compat.json

# Both
npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  --schema /tmp/schema.cql --prepared /tmp/prepared_statements.ndjson \
  | tee /tmp/keyspaces-compat.json

# Schema on stdin (only valid without --prepared)
echo "CREATE TABLE app.users (id uuid PRIMARY KEY, email text);" \
  | npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  | tee /tmp/keyspaces-compat.json

What it detects

See keyspaces-unsupported-features.md for the authoritative list and migration guidance. The tool flags:

From schema (CQL DDL):

CREATE INDEX — secondary indexes (per table).
CREATE TRIGGER — triggers (per table).
CREATE MATERIALIZED VIEW — attached to base table.
CREATE FUNCTION — user-defined functions (counted globally).
CREATE AGGREGATE — user-defined aggregates (counted globally).

From prepared statements:

LWT inside BEGIN UNLOGGED BATCH — any conditional (IF NOT EXISTS, IF EXISTS, IF <col>=…) inside an unlogged batch.
Aggregate calls — COUNT(, MIN(, MAX(, SUM(, AVG( anywhere in a SELECT.
Per-table USING TTL — informational only, not an issue; used by Mode 2 to mark tables as TTL-driven for pricing.

UDF usage is intentionally not detected from prepared statements — CREATE FUNCTION in schema is the source of truth.

Output shape

{
  "source": "compatibility-check",
  "input":   { "schema": "<path or null>", "prepared": "<path or null>" },
  "has_issues": true | false,
  "summary": {
    "total_issues": N,
    "schema": {
      "total_issues": N,
      "keyspaces_affected": N,
      "tables_affected": N,
      "functions": N,
      "aggregates": N
    } | null,
    "query_patterns": {
      "lwt_in_unlogged_batch": N,
      "aggregations": N,
      "ttl_tables": N
    } | null
  },
  "details": {
    "schema": {
      "functions": N,
      "aggregates": N,
      "keyspaces": {
        "<keyspace>": {
          "<table>": {
            "indexes":           ["idx_name", …],
            "triggers":          ["trg_name", …],
            "materializedViews": ["view_name", …]
          }
        }
      }
    } | null,
    "query_patterns": {
      "lwt_in_unlogged_batch": [ { "prepared_id": "...", "query_string": "..." } ],
      "aggregations":          [ { "prepared_id": "...", "function": "COUNT", "query_string": "..." } ],
      "ttl_tables":            { "<ks>.<table>": { "uses_ttl": true, "ttl_values": [3600, 86400] } }
    } | null
  }
}

Display rules

Compatibility is binary. Every detected feature is not supported. Do not hedge with qualifiers like "supported with restrictions", "supported with caveats", "works when cardinality is high", or "may cause hot partitions" — those qualifiers do not apply here and mislead customers into building unsupported designs.

Present in this order:

One-line verdict — if has_issues is false, say the schema/workload is compatible with Amazon Keyspaces and stop. Otherwise continue.
Per-keyspace / per-table breakdown — for every keyspace in details.schema.keyspaces, list affected tables and their flagged features. Show the feature name (index / trigger / materialized view) and the object name.
Global counts — details.schema.functions and details.schema.aggregates (numbers only; names are not captured).
Per-query breakdown — for each entry in details.query_patterns.lwt_in_unlogged_batch and .aggregations, show the offending query_string truncated to roughly 200 characters. Include the prepared_id to help the user find it in their codebase.
ttl_tables (informational) — list as "tables using USING TTL: …" so the user can verify the TTL pricing signal Mode 2 uses.
Migration guidance — for each flagged category, offer guidance from keyspaces-unsupported-features.md. Keep guidance to what to do instead, not why the feature is limited.

PDF generation is not supported for Mode 3

Mode 3 produces a compatibility report only. generate-pdf.ts expects pricing JSON and will fail on a compatibility JSON. If the user wants a combined compatibility + pricing PDF, direct them to Mode 2 — it includes compatibility automatically when schema or prepared is supplied.

Follow-ups

"Can I automate this in CI?" — yes; check-compatibility.ts returns non-zero exit only on usage errors, not on has_issues. Check .has_issues in the JSON to fail a pipeline.

"How do I fix each issue?" — see migration guidance in keyspaces-unsupported-features.md.

"Does this catch everything?" — no. Data-type and CQL-syntax-level differences (the full functional-differences list) are not checked. Link the user to the official Keyspaces functional differences page.

/amazon-keyspaces

referencesmode-3-compatibility.md