Row CRUD Endpoints

Four endpoints for single-row operations on Row molecule collections. These provide relational-style CRUD with primary key identity, atomic updates, and duplicate detection.

Architecture note: Row CRUD is part of RelationalTable — structured storage with chain binding encoding. It does not generate semantic embeddings. For semantic search over row data, use Catalog.index() separately.

---

POST /row/insert/

Insert a single row into a Row molecule collection.

Request Body

Parameter	Type	Required	Description
db_name	string	✅	Database name
namespace	string	✅	Namespace (must exist and use Row molecule)
row	object	✅	Row data including the primary key field
template_schema	object	✅	Row molecule schema with primary_key defined

Behavior

• Checks for duplicate primary key — returns 409 if exists
• Encodes row using chain binding: pk ⊛ (f₁⊛v₁) ⊛ (f₂⊛v₂) ⊛ ...
• Row ID is assigned atomically (safe for concurrent inserts)
• The namespace must have been created first via /build_ingest_data/ with a Row schema

Response

{
  "status": "success",
  "pk_field": "id",
  "pk_value": "E011",
  "row_id": 10,
  "namespace": "employees",
  "db_name": "my_db",
  "note": "Row stored. For semantic search, use Catalog.index() or Catalog.reindex()."
}

Error Responses

Status	Condition
400	Row missing primary key, or namespace uses a non-Row molecule
404	Namespace not found
409	Duplicate primary key
500	Unexpected internal error

---

POST /row/get/

Retrieve a row by primary key (O(1) lookup).

Request Body

Parameter	Type	Required	Description
db_name	string	✅	Database name
namespace	string	✅	Namespace
pk_field	string	✅	Primary key field name
pk_value	string	✅	Primary key value to look up

Response

{
  "status": "success",
  "row_id": 10,
  "data": { "id": "E011", "name": "Zara", "department": "Engineering" },
  "namespace": "employees",
  "db_name": "my_db"
}

Error Responses

Status	Condition
404	Namespace or row not found
500	Unexpected internal error

---

POST /row/update/

Atomically update a row by primary key.

Request Body

Parameter	Type	Required	Description
db_name	string	✅	Database name
namespace	string	✅	Namespace
pk_field	string	✅	Primary key field name
pk_value	string	✅	Primary key value identifying the row
updates	object	✅	Fields to update. Cannot include pk_field
template_schema	object	❌	Schema for re-encoding. Falls back to stored schema

Behavior

Merges updates into existing row data, then re-encodes the entire row atomically. The primary key cannot be updated. Semantic embeddings are not regenerated — use Catalog.reindex() if text fields changed.

Response

{
  "status": "success",
  "method": "atomic_row_update",
  "pk_field": "id",
  "pk_value": "E011",
  "row_id": 10,
  "old_values": { "salary": "95000" },
  "new_values": { "salary": "105000" },
  "namespace": "employees",
  "db_name": "my_db",
  "note": "Row updated. For semantic search, use Catalog.reindex() if text fields changed."
}

Error Responses

Status	Condition
400	Attempted to update the primary key field
404	Namespace or row not found
500	Unexpected internal error

---

POST /row/delete/

Delete a row by primary key.

Request Body

Parameter	Type	Required	Description
db_name	string	✅	Database name
namespace	string	✅	Namespace
pk_field	string	✅	Primary key field name
pk_value	string	✅	Primary key value to delete

Response

{
  "status": "success",
  "deleted": { "pk_field": "id", "pk_value": "E011", "row_id": 10 },
  "namespace": "employees",
  "db_name": "my_db"
}

Error Responses

Status	Condition
404	Namespace or row not found
500	Unexpected internal error

---

POST /row/delete_filter/

Bulk delete rows matching a field value.

Request Body

Parameter	Type	Required	Description
db_name	string	✅	Database name
namespace	string	✅	Namespace
field	string	✅	Field to filter on
value	string	✅	Value to match (exact)

Response

{
  "status": "success",
  "rows_deleted": 3,
  "filter": { "field": "department", "value": "Engineering" },
  "namespace": "employees",
  "db_name": "my_db"
}

Error Responses

Status	Condition
404	Namespace not found
500	Unexpected internal error

---

Notes

• All Row CRUD endpoints require the namespace to be created with "molecule": "Row" and a primary_key defined in the schema.
• The primary key is immutable — attempting to update it returns 400.
• delete_filter uses exact string matching — it does not support operators.
• Row CRUD does not touch semantic embeddings. Use Catalog.reindex() after updates if semantic search is needed.

---

Schema Example

ROW_SCHEMA = {
    "molecule": "Row",
    "primary_key": {"name": "id"},
    "fields": {
        "id":         {"encoding": "exact"},
        "name":       {"encoding": "exact"},
        "department": {"encoding": "exact"},
        "salary":     {"encoding": "numeric"},
    }
}