2024-01-22 00:50:35 +03:00
# DDL: Namespace
## CREATE NAMESPACE
Creates a new namespace within the specified or default database.
2023-12-06 20:38:31 +03:00
Namespaces group various database components, including tables and views. When not explicitly specified, namespace designations default to `dbo` .
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
< create-namespace > ::=
2024-01-22 00:50:35 +03:00
CREATE NAMESPACE [< database > .] < namespace > [ < as-of-time > ]
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### API
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
+$ create-namespace
database-name=@tas
name=@tas
2024-01-22 00:50:35 +03:00
as-of=(unit as-of)
2023-12-06 20:38:31 +03:00
==
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### 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.
2023-12-06 20:38:31 +03:00
**`< 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.
2024-01-06 21:15:32 +03:00
**`< as-of-time > `**
2024-01-22 00:50:35 +03:00
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
2023-12-06 20:38:31 +03:00
2024-08-07 17:00:33 +03:00
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.
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### Produced Metadata
2024-07-22 18:33:07 +03:00
Schema timestamp
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### Exceptions
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
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
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### Example
`CREATE NAMESPACE my-namespace`
## ALTER NAMESPACE
*supported in urQL parser, not yet supported in Obelisk*
2023-12-06 20:38:31 +03:00
Transfer an existing user `<table>` or `<view>` to another `<namespace>` .
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
< alter-namespace > ::=
2024-01-22 00:50:35 +03:00
ALTER NAMESPACE [ < database > . ] < namespace >
2023-12-06 20:38:31 +03:00
TRANSFER { TABLE | VIEW } [ < db-qualifer > ]{ < table > | < view > }
2024-01-06 21:15:32 +03:00
[ < as-of-time > ]
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### API
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
+$ alter-namespace
$: %alter-namespace
database-name=@tas
source-namespace=@tas
object-type=object-type
target-namespace=@tas
target-name=@tas
2024-01-22 00:50:35 +03:00
as-of=(unit as-of)
2023-12-06 20:38:31 +03:00
==
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### Arguments
2023-12-06 20:38:31 +03:00
**`< 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.
2024-01-06 21:15:32 +03:00
**`< as-of-time > `**
2024-01-22 00:50:35 +03:00
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.
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### Remarks
2023-12-06 20:38:31 +03:00
This command mutates the state of the Obelisk agent.
Objects cannot be transferred in or out of namespace *sys* .
2024-01-22 00:50:35 +03:00
### Produced Metadata
2024-07-22 18:33:07 +03:00
Schema timestamp
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### 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
2023-12-06 20:38:31 +03:00
`<table>` or `<view>` does not exist
2024-01-22 00:50:35 +03:00
## DROP NAMESPACE
*supported in urQL parser, not yet supported in Obelisk*
Deletes a `<namespace>` and all its associated objects when `FORCE` specified.
2023-12-06 20:38:31 +03:00
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
< drop-namespace > ::=
2024-01-22 00:50:35 +03:00
DROP NAMESPACE [ FORCE ] [ < database > . ] < namespace >
2024-01-06 21:15:32 +03:00
[ < as-of-time > ]
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### API
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
+$ drop-namespace
$:
%drop-namespace
database-name=@tas
name=@tas
force=?
2024-01-22 00:50:35 +03:00
as-of=(unit as-of)
2023-12-06 20:38:31 +03:00
==
2024-04-28 19:22:56 +03:00
```
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
### Arguments
2023-12-06 20:38:31 +03:00
**`FORCE`**
2024-01-22 00:50:35 +03:00
Optionally force deletion of `<namespace>` , dropping all objects associated with the namespace.
2023-12-06 20:38:31 +03:00
**`< namespace > `**
The name of `<namespace>` to delete.
2024-01-06 21:15:32 +03:00
**`< as-of-time > `**
2024-04-28 19:22:56 +03:00
Timestamp of namespace deletion. Defaults to `NOW` (current time). When specified timestamp must be greater than both the latest database schema and content timestamps.
2024-01-22 00:50:35 +03:00
### Remarks
2023-12-06 20:38:31 +03:00
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.
2024-01-22 00:50:35 +03:00
### Produced Metadata
2024-07-22 18:33:07 +03:00
Schema timestamp
2024-01-22 00:50:35 +03:00
### Exceptions
2023-12-06 20:38:31 +03:00
2024-01-22 00:50:35 +03:00
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.