schema.graphql

"""
A flexible JSON-like value.
Accepts objects, arrays, strings, numbers, booleans, or null.
Useful for schemaless or mixed content.
"""
scalar Any

"""
Arbitrary-precision integer for values larger than 32-bit/64-bit ranges.
Input may be provided as a JSON number or string; tooling may return it as a
string to avoid precision loss. Use `Long` for 64-bit integers when possible.
"""
scalar BigInt

"""
Binary large object. Represents binary data such as images or files.
Typically encoded as Base64 in JSON.
"""
scalar Blob

"""
true or false
"""
scalar Boolean

"""
Raw bytes. Typically encoded/transported as Base64 in JSON.
Use when you need deterministic binary data that is not a large file.
"""
scalar Bytes

"""
Date/time scalar. Recommended format: RFC 3339/ISO-8601 (e.g.,
"2025-12-02T19:44:00Z"). Represents an absolute timestamp.
"""
scalar Date

"""
A signed double-precision floating-point value
"""
scalar Float

"""
ID (serialized as a String): A unique identifier that's often used to refetch an
object or as the key for a cache. Although it's serialized as a String, an ID is
not intended to be human‐readable.
"""
scalar ID

"""
A signed 32‐bit integer
"""
scalar Int

"""
64-bit signed integer. Some clients may serialize values as strings to
preserve precision across environments.
"""
scalar Long

"""
A UTF‐8 character sequence
"""
scalar String

"""
Attach to an object type to persist it as a table.

Example:
```
type Post @table(table: "posts", database: "blog") {
id: ID @primaryKey
title: String @indexed(type: "fulltext")
body: String
createdAt: Date @createdTime
updatedAt: Date @updatedTime
}
```
"""
directive @table(
	"""
	Explicit table name. If omitted, a sensible default derived from the
	type name will be used.
	"""
	table: String
	"""
	Logical database/namespace to place this table in.
	"""
	database: String
	"""
	Default time-to-live (TTL) for records in seconds. Use a positive value to
	enable automatic expiration; omit or set to 0 to disable.
	"""
	expiration: Int
	"""
	Enable auditing for create/update/delete operations.
	"""
	audit: Boolean
	"""
	The amount of time after expiration before a record can be evicted (defaults to zero).
	"""
	eviction: Int
	"""
	The interval for scanning for expired records (defaults to one quarter of the
	total of expiration and eviction).
	"""
	scanInterval: Int
	"""
	By default, all tables within a replicated database will be replicated. Transactions
	are replicated atomically, which may involve data across multiple tables. However,
	you can also configure replication for individual tables, and disable and exclude
	replication for specific tables in a database by setting replicate to false in the
	table definition.
	"""
	replicate: Boolean
) on OBJECT

"""
Expose the table via the REST API. When applied to a `@table` type, routes are
generated using the type name or the provided alias.
"""
directive @export(
	"""
	Optional alias to use for REST endpoints. If omitted, the type/table name is
	used.
	"""
	name: String
	"""
	REST support is, by default, turned on for any exported resource. You may specify
	false to disable this automatic API support.
	"""
	rest: Boolean
	"""
	MQTT support is, by default, turned on for any exported resource. You may specify
	false to disable this automatic API support.
	"""
	mqtt: Boolean
) on OBJECT
"""
As a NoSQL database, HarperDB supports heterogeneous records (also referred to as
documents), so you can freely specify additional properties on any record. If you
do want to restrict the records to only defined properties, you can always do that
by adding the sealed directive.
"""
directive @sealed on OBJECT

"""
Marks the primary key field for the table. The value must be unique per record
and is used for lookups, updates, and relationships.
"""
directive @primaryKey on FIELD_DEFINITION

"""
Allows enumeration over a computed field, causing it to be included in serialized responses. (Non-computed fields are always enumerable, and don't need to be flagged.)
"""
directive @enumerable on FIELD_DEFINITION

"""
Flags the field as containing the expiration time of the entry.
"""
directive @expiresAt on FIELD_DEFINITION

"""
Permit access to the field based on the named roles, only.
"""
directive @allow(role: String) on FIELD_DEFINITION

"""
Create an index for the annotated field. Supports traditional and vector/ANN
index types.
"""
directive @indexed(
	"""
	Optional index type, e.g. "HNSW"
	"""
	type: String
	"""
	Distance metric for vector indexes (e.g., "euclidean", "cosine").
	Ignored for non-vector index types.
	"""
	distance: String
	"""
	Construction effort/recall parameter (HNSW). Higher values improve recall at
	the cost of build time and memory.
	"""
	efConstruction: Int
	"""
	Maximum number of bi-directional connections per node (HNSW).
	Typical range: 4–64.
	"""
	M: Int
	"""
	Routing optimization level for search graphs (implementation-specific).
	"""
	optimizeRouting: Int
	"""
	Additional multiplier for graph links (implementation-specific).
	"""
	mL: Int
	"""
	Search-time effort/recall parameter used during construction (implementation-
	specific). Larger values typically yield better accuracy.
	"""
	efConstructionSearch: Int
) on FIELD_DEFINITION

"""
Define a derived field whose value is computed from other fields.
Useful for denormalized or presentation-friendly data.
"""
directive @computed(
	"""
	Computation expression or reference describing how to derive this field from
	other fields (engine-specific syntax).
	"""
	from: String
	"""
	Increment when the computation changes to trigger recomputation.
	"""
	version: Int
) on FIELD_DEFINITION
"""
Automatically sets this field to the record's creation timestamp. The server
assigns the value on insert.
"""
directive @createdTime on FIELD_DEFINITION
"""
Automatically updates this field to the current timestamp whenever the record
is updated.
"""
directive @updatedTime on FIELD_DEFINITION
"""
Declares a relationship to another record or records.
Use on fields that should resolve to related entities by ID.
"""
directive @relationship(
	"""
	Name of field in THIS table containing foreign key(s) (for one-to-many or many-to-many).
	"""
	from: String
	"""
	Name of field in OTHER table containing foreign key (for one-to-one or many-to-one).
	"""
	to: String
) on FIELD_DEFINITION