DESCRIBE
– provide human-readable description of a schema or a
schema object
DESCRIBE SCHEMA [ AS {DDL | SDL | TEXT [ VERBOSE ]} ];
DESCRIBE schema-type name [ AS {DDL | SDL | TEXT [ VERBOSE ]} ];
where schema-type is one of
OBJECT
ANNOTATION
CONSTRAINT
FUNCTION
LINK
MODULE
PROPERTY
SCALAR TYPE
TYPE
DESCRIBE
generates a human-readable description of a schema object.
The output of a DESCRIBE
command is a str
, although
it cannot be used as an expression in queries.
There are three output formats to choose from:
Provide a valid DDL definition.
The DDL generated is a complete valid definition of the particular schema object assuming all the other referenced schema objects already exist.
This is the default format.
Provide an SDL definition.
The SDL generated is a complete valid definition of the particular schema object assuming all the other referenced schema objects already exist.
Provide a human-oriented definition.
The human-oriented definition generated is similar to SDL, but it includes all the details that are inherited (if any).
The VERBOSE mode enables displaying additional details, such as annotations and constraints, which are otherwise omitted.
When the DESCRIBE
command is used with the SCHEMA
the result is a definition of the entire database schema. Only the
AS DDL option is available for schema description.
The DESCRIBE
command can specify the type of schema object that it
should generate the description of:
Match any module level schema object with the specified name.
This is the most general use of the DESCRIBE
command. It does
not match modules (and other
globals that cannot be uniquely identified just by the name).
Match only annotations with the specified name.
Match only constraints with the specified name.
Match only functions with the specified name.
Match only links with the specified name.
Match only modules with the specified name.
Match only properties with the specified name.
Match only scalar types with the specified name.
Match only object types with the specified name.
Consider the following schema:
abstract type Named {
required property name -> str {
delegated constraint exclusive;
}
}
type User extending Named {
required property email -> str {
annotation title := 'Contact email';
}
}
Here are some examples of a DESCRIBE
command:
db>
DESCRIBE OBJECT User;
{ "CREATE TYPE default::User EXTENDING default::Named { CREATE REQUIRED SINGLE PROPERTY email -> std::str { CREATE ANNOTATION std::title := 'Contact email'; }; };" }
db>
DESCRIBE OBJECT User AS SDL;
{ "type default::User extending default::Named { required single property email -> std::str { annotation std::title := 'Contact email'; }; };" }
db>
DESCRIBE OBJECT User AS TEXT;
{ 'type default::User extending default::Named { required single link __type__ -> schema::Type { readonly := true; }; required single property email -> std::str; required single property id -> std::uuid { readonly := true; }; required single property name -> std::str; };' }
db>
DESCRIBE OBJECT User AS TEXT VERBOSE;
{ "type default::User extending default::Named { required single link __type__ -> schema::Type { readonly := true; }; required single property email -> std::str { annotation std::title := 'Contact email'; }; required single property id -> std::uuid { readonly := true; constraint std::exclusive; }; required single property name -> std::str { constraint std::exclusive; }; };" }
db>
DESCRIBE SCHEMA;
{ "CREATE MODULE default IF NOT EXISTS; CREATE ABSTRACT TYPE default::Named { CREATE REQUIRED SINGLE PROPERTY name -> std::str { CREATE DELEGATED CONSTRAINT std::exclusive; }; }; CREATE TYPE default::User EXTENDING default::Named { CREATE REQUIRED SINGLE PROPERTY email -> std::str { CREATE ANNOTATION std::title := 'Contact email'; }; };" }
The DESCRIBE
command also warns you if there are standard library
matches that are masked by some user-defined object. Consider the
following schema:
module default {
function len(v: tuple<float64, float64>) -> float64 using (
SELECT (v.0 ^ 2 + v.1 ^ 2) ^ 0.5
);
}
So within the default
module the user-defined function len
(computing the length of a vector) masks the built-ins:
db>
DESCRIBE FUNCTION len AS TEXT;
{ 'function default::len(v: tuple<std::float64, std::float64>) -> std::float64 using (SELECT (((v.0 ^ 2) + (v.1 ^ 2)) ^ 0.5) ); # The following builtins are masked by the above: # function std::len(bytes: std::bytes) -> std::int64 { # volatility := \'Immutable\'; # using sql $$ # SELECT length("bytes")::bigint # $$ # ;}; # function std::len(str: std::str) -> std::int64 { # volatility := \'Immutable\'; # using sql $$ # SELECT char_length("str")::bigint # $$ # ;}; # function std::len(array: array<anytype>) -> std::int64 { # volatility := \'Immutable\'; # using sql $$ # SELECT cardinality("array")::bigint # $$ # ;};', }