`POST /join/`¶

Joins two namespaces within the same database. Supports INNER, LEFT, RIGHT, and FULL OUTER joins with field-level join conditions.

Request¶

Query Parameters:

Parameter	Description
`db_name`	Name of the database containing both namespaces

Body:

Parameter	Type	Required	Default	Description
`left_namespace`	string	✅	—	Left-side namespace
`right_namespace`	string	✅	—	Right-side namespace
`join_type`	string	✅	—	One of: `inner`, `left`, `right`, `full`
`join_conditions`	list	✅	—	Field pairs to join on
`left_prefix`	string	❌	`""`	Prefix for left-side columns in output
`right_prefix`	string	❌	`""`	Prefix for right-side columns in output
`limit`	int	❌	—	Max rows to return
`key_separator`	string	❌	`"."`	Separator used when combining prefixed field names

Join condition object:

Field	Type	Description
`left_field`	string	Field name in the left namespace
`right_field`	string	Field name in the right namespace
`operator`	string	Join operator — typically `"eq"`

Behavior¶

Performs the join in Rust across both namespaces using RocksDB row metadata. Both namespaces must exist within the same db_name. Column name conflicts between namespaces are resolved using left_prefix and right_prefix.

Responses¶

200 OK¶

{
  "total_rows": 5,
  "execution_time_ms": 24.1,
  "rows": [
    {
      "emp.id":         "E001",
      "emp.name":       "Alice",
      "emp.department": "Engineering",
      "ord.order_id":   "O001",
      "ord.product":    "Laptop",
      "ord.amount":     "2500"
    }
  ]
}

Field	Description
`total_rows`	Number of joined rows returned
`execution_time_ms`	Query execution time
`rows`	Array of joined row objects

Error Responses¶

Status	Condition
`404`	One or both namespaces not found
`500`	Unexpected internal error

Notes¶

Both namespaces must be in the same db_name.
Use left_prefix and right_prefix to avoid column name collisions.
INNER join returns only rows with matches in both sides.
LEFT join returns all left rows, with nulls for unmatched right rows.

Example¶

import requests

SERVER_URL = "http://18.220.128.24:8000"
API_KEY    = "yourapitoken"

def join(db_name: str, query: dict) -> dict:
    response = requests.post(
        f"{SERVER_URL}/join/",
        headers={"X-API-Key": API_KEY},
        params={"db_name": db_name},
        json=query,
    )
    response.raise_for_status()
    return response.json()


result = join("my_db", {
    "left_namespace":  "employees",
    "right_namespace": "orders",
    "join_type":       "inner",
    "join_conditions": [
        {"left_field": "id", "right_field": "employee_id", "operator": "eq"}
    ],
    "left_prefix":  "emp",
    "right_prefix": "ord",
})
print(result)

Expected output:

{
  "total_rows": 9,
  "execution_time_ms": 21.3,
  "rows": [
    { "emp.id": "E001", "emp.name": "Alice", "ord.order_id": "O001", "ord.product": "Laptop" }
  ]
}

POST /join/¶