SCHEMA, the
standard’s name for the same concept. A schema is a complete namespace
path, optionally qualified by a database; a nested path occupies one
backtick-quoted identifier with $ between components, such as
analytics.`team$features`. A namespace, as a separate keyword, names
one path component, relative to an explicit parent schema or the session’s
current schema — it cannot contain $ or be qualified with a database.
SCHEMA never accepts IN. NAMESPACE accepts IN followed by a complete
schema identifier. Names are lowercased unless quoted.
CREATE SCHEMA and CREATE NAMESPACE
Create a namespace using its complete schema path:$ between its
components: db1.`ns1$ns2` creates ns2 inside ns1 in database db1.
Both forms create namespaces in the same catalog, and missing ancestors are
created automatically — the part before the first dot is always the
database. public is the database’s root namespace, which is never created
or dropped.
IF NOT EXISTS makes the statement a no-op rather than an error when the
namespace is already there, though it does not replace an existing
namespace’s properties. Without it, an existing target is an error.
Properties are string values stored on the target only; implicitly created
ancestors receive no properties, and duplicate property keys are errors.
The result has operation, name, and status columns. The operation is
CREATE SCHEMA for either spelling; the name is the resolved path and the
status is created.
Creation requires
CREATE NAMESPACE on the database and the parent
namespace — the same privileges the
namespace REST API checks. The caller becomes the
owner of each newly created namespace, including implicitly created
ancestors. See Grant for the full privilege
list a namespace accepts.ALTER SCHEMA and ALTER NAMESPACE
SET adds or replaces the listed string properties, preserving other keys.
UNSET removes the listed keys; a missing key is ignored. Lists must be
nonempty, and duplicate keys are errors. Quote a key containing punctuation,
for example SET ("owner.team" = 'search').
Each statement updates metadata atomically and preserves unrelated
concurrent changes. Metadata changes do not change ownership or grants. Use
DESCRIBE to read the updated properties. A missing namespace is an error.
Requires
USAGE on the database and the namespace, and OWNERSHIP on the
namespace itself.ALTER metadata is supported by native manifest-backed databases. Legacy
directory and external catalogs report an unsupported-operation error. The
implicit public root and the read-only system database cannot be
altered.operation, name, and status columns, with operation
ALTER SCHEMA for either spelling and status altered.
DESCRIBE SCHEMA and DESCRIBE NAMESPACE
name (the complete $-joined schema path) and
properties (a JSON object). An unannotated namespace returns {}. A
missing namespace is an error. DESC is an alias for DESCRIBE.
Requires
USAGE on the database and the namespace.SHOW SCHEMAS and SHOW NAMESPACES
SHOW SCHEMAS returns complete paths in the current database, recursively,
including public when the caller can use it. It does not accept IN.
SHOW NAMESPACES lists only immediate child names under the session’s
current schema. IN selects a different parent schema, optionally in
another database — use IN public for the current database’s root, or
IN analytics.public for another database’s root. A missing parent is an
error.
Both forms return a sorted name column and omit namespaces the caller
cannot use. Large listings that exceed 10,000 namespaces, or recursive
listings deeper than 32 levels, return an error suggesting a narrower
listing.
DROP SCHEMA and DROP NAMESPACE
RESTRICT, refuses a namespace with children or objects —
tables, views and other objects inside must be dropped explicitly first. In
native manifest-backed databases, CASCADE instead removes the namespace
and all descendant bindings atomically in one catalog commit, then submits
a background job that cleans up their storage; deployments without cascade
support reject it. A storage integration used by an attached database
blocks the drop of its namespace.
Requires
USAGE and OWNERSHIP on the namespace. A dropped Secret is
eligible for immediate deletion even when jobs still reference it: a
process that already holds the value keeps it for the rest of its run, but
a later launch that needs the Secret can fail once it’s gone.RESTRICT returns operation, name, and status, with status dropped
or not_found. CASCADE returns operation, job_id, and status, with
status dropping, or an empty job ID and not_found for a missing target
with IF EXISTS. Inspect a cascade drop’s child jobs with
SHOW JOBS FOR JOB. Both spellings report operation
DROP SCHEMA.
Correcting invalid syntax
What to read next
Database
Attaching the database a namespace lives in.
Namespace
The SDK equivalent, and how a namespace fits the catalog hierarchy.
Table
Creating tables inside a namespace.