urQL/docs/03-ddl-namespace.md

DDL: Namespace

CREATE NAMESPACE

Creates a new namespace within the specified or default database.

Namespaces group various database components, including tables and views. When not explicitly specified, namespace designations default to dbo.

<create-namespace> ::= 
  CREATE NAMESPACE [<database>.] <namespace> [ <as-of-time> ]

API

+$  create-namespace 
    database-name=@tas 
    name=@tas
    as-of=(unit as-of)
  ==

Arguments

** <database>** The database within which to create the namespace. When specified overrides the default database.

If not explicitly qualified, it defaults to the Obelisk agent's current database.

<namespace> This is a user-defined name for the new namespace. It must adhere to the hoon term naming standard.

Note: The "sys" namespace is reserved for system use.

<as-of-time> Timestamp of namespace creation. Defaults to NOW (current time). When specified timestamp must be greater than both the latest database schema and content timestamps.

Remarks

This command mutates the state of the Obelisk agent. However, it does not generate the state change after query in script because it is a trivial change that cannot effect a query.

Produced Metadata

Schema timestamp

Exceptions

schema changes must be by local agent database <database> does not exist namespace <namespace> as-of schema time out of order namespace <namespace> as-of content time out of order namespace <namespace> already exists

Example

CREATE NAMESPACE my-namespace

ALTER NAMESPACE

supported in urQL parser, not yet supported in Obelisk

Transfer an existing user <table> or <view> to another <namespace>.

<alter-namespace> ::=
  ALTER NAMESPACE [ <database>. ] <namespace>
    TRANSFER { TABLE | VIEW } [ <db-qualifer> ]{ <table> | <view> }
    [ <as-of-time> ]

API

+$  alter-namespace
  $:  %alter-namespace
    database-name=@tas
    source-namespace=@tas
    object-type=object-type
    target-namespace=@tas
    target-name=@tas
    as-of=(unit as-of)
  ==

Arguments

<namespace> Name of the target namespace into which the object is to be transferred.

TABLE | VIEW Indicates the type of the target object.

<table> | <view> Name of the object to be transferred to the target namespace.

<as-of-time> Timestamp of namespace update. Defaults to NOW (current time). When specified, the timestamp must be greater than both the latest database schema and content timestamps.

Remarks

This command mutates the state of the Obelisk agent.

Objects cannot be transferred in or out of namespace sys.

Produced Metadata

Schema timestamp

Exceptions

schema changes must be by local agent database <database> does not exist namespace <namespace> as-of schema time out of order namespace <namespace> as-of content time out of order namespace <namespace> does not exist alter namespace state change after query in script <table> or <view> does not exist

DROP NAMESPACE

supported in urQL parser, not yet supported in Obelisk

Deletes a <namespace> and all its associated objects when FORCE specified.

<drop-namespace> ::= 
  DROP NAMESPACE [ FORCE ] [ <database>. ] <namespace>
  [ <as-of-time> ]

API

+$  drop-namespace
  $:
    %drop-namespace 
    database-name=@tas 
    name=@tas 
    force=?
    as-of=(unit as-of)
  ==

Arguments

FORCE Optionally force deletion of <namespace>, dropping all objects associated with the namespace.

<namespace> The name of <namespace> to delete.

<as-of-time> Timestamp of namespace deletion. Defaults to NOW (current time). When specified timestamp must be greater than both the latest database schema and content timestamps.

Remarks

This command mutates the state of the Obelisk agent.

Only succeeds when no populated <table>s are in the namespace, unless FORCE is specified, possibly resulting in cascading object drops described in DROP TABLE.

The namespaces dbo and sys cannot be dropped.

Produced Metadata

Schema timestamp

Exceptions

schema changes must be by local agent namespace <namespace> does not exist namespace <namespace> as-of schema time out of order namespace <namespace> as-of content time out of order drop namespace state change after query in script <namespace> has populated tables and FORCE was not specified.