urQL/docs/ref-ch10-alter.md

ALTER INDEX

Modifies the structure of an existing <index> on a user <table> or <view>.

<alter-index> ::=
  ALTER [ UNIQUE ] [ NONCLUSTERED | CLUSTERED ] INDEX [ <db-qualifer> ]<index>
    ON { <table> | <view> }
    [ ( <column> [ ASC | DESC ] [ ,...n ] ) ]
    { DISABLE | RESUME}

API

+$  alter-index
  $:
    %alter-index
    name=qualified-object
    object=qualified-object
    columns=(list ordered-column)
    action=index-action
  ==

Arguments

UNIQUE Specifies that no two rows are permitted to have the same index key value.

NONCLUSTERED | CLUSTERED CLUSTERED creates an index in which the logical order of the key values determines the physical order of the corresponding rows in a table. A <table> or <view> can have only one clustered index at a time.

[ <db-qualifer> ]<index> Specifies the target index.

<table> | <view> Name of the underlying object of the index.

<column> [ ASC | DESC ] [ ,...n ] List of column names in the target table. This list represents the sort hierarchy and optionally specifies the sort direction for each level. The default sorting is ASC (ascending).

DISABLE | RESUME Used to disable an active index or resume a disabled index.

Remarks

This command mutates the state of the Obelisk agent.

Cannot alter primary key and foreign key indices.

RESUME will rebuild the index if the underlying object is dirty.

Note: Further investigation into hoon ordered maps is needed to determine what exactly "clustered" means in hoon.

Produced Metadata

update <database>.sys.indices

Exceptions

index name does not exist for table table does not exist column does not exist UNIQUE specified and existing values are not unique for the column(s) specified

ALTER NAMESPACE

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

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

API

+$  alter-namespace
  $:
    %alter-namespace
    database-name=@tas
    source-namespace=@tas
    object-type=object-type
    target-namespace=@tas
    target-name=@tas
  ==

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..

Remarks

This command mutates the state of the Obelisk agent.

Objects cannot be transferred in or out of namespace sys.

Produced Metadata

update <database>.sys.tables update <database>.sys.views

Exceptions

namespace does not exist <table> or <view> does not exist

ALTER PROCEDURE

TBD

<alter-proc> ::=
  ALTER { PROC | PROCEDURE }
    [<db-qualifer>]<procedure>
    [ { #<parameter> <data-type> } ] [ ,...n ]
  AS { <urql command>; | *hoon } [ ;...n ]

ALTER TABLE

Modify the columns and/or <foreign-key>s of an existing <table>.

<alter-> ::=
  ALTER TABLE [ <db-qualifer> ]{ <table> }
    { ADD COLUMN ( <column>  <aura> [ ,... n ] )
      | ALTER COLUMN ( <column>  <aura> [ ,... n ] )
      | DROP COLUMN ( <column> [ ,... n ] )
      | ADD FOREIGN KEY <foreign-key> (<column> [ ,... n ])
        REFERENCES [<namespace>.]<table> (<column> [ ,... n ])
        [ ON DELETE { NO ACTION | CASCADE } ]
        [ ON UPDATE { NO ACTION | CASCADE } ]
        [ ,... n ]
      | DROP FOREIGN KEY ( <foreign-key> [ ,... n ] } )

Example:

ALTER TABLE my-table
DROP FOREIGN KEY fk-1, fk-2

API

+$  alter-table
  $:
    %alter-table
    table=qualified-object
    alter-columns=(list column)
    add-columns=(list column)
    drop-columns=(list @tas)
    add-foreign-keys=(list foreign-key)
    drop-foreign-keys=(list @tas)
  ==

Arguments

<table> Name of <table> to alter.

ADD | ALTER COLUMN ( <column> <aura> [ ,... n ] ) Denotes a list of user-defined column names and associated auras. ALTER is used to change the aura of an existing column.

Names must follow the Hoon term naming standard. See ref-ch02-types

DROP COLUMN ( <column> [ ,... n ] ) Denotes a list of existing column names to delete from the <table> structure.

[ NONCLUSTERED | CLUSTERED ] ( <column> [ ,... n ] These are column names in the required unique primary index. Defining the index as CLUSTERED is optional.

ADD | DROP The action is to add or drop a foreign key.

<foreign-key> ( <column> [ ASC | DESC ] [ ,... n ] This is a user-defined name for <foreign-key>. It must adhere to the hoon term naming standard. This list comprises column names in the table for association with a foreign table along with sort ordering. Default is ASC (ascending).

<table> ( <column> [ ,... n ] Referenced foreign <table> and columns. Count and associated column auras must match the specified columns from the new <table> and comprise a UNIQUE index on the referenced foreign <table>.

ON DELETE { NO ACTION | CASCADE | SET DEFAULT } This argument specifies the action to be taken on the rows in the table that have a referential relationship when the referenced row is deleted from the foreign table.

• NO ACTION (default)

The Obelisk agent raises an error and the delete action on the row in the parent foreign table is aborted.

• CASCADE

Corresponding rows are deleted from the referencing table when that row is deleted from the parent foreign table.

• SET DEFAULT

All the values that make up the foreign key in the referencing row(s) are set to their bunt (default) values when the corresponding row in the parent foreign table is deleted.

The Obelisk agent raises an error if the parent foreign table has no entry with bunt values.

ON UPDATE { NO ACTION | CASCADE | SET DEFAULT } This argument specifies the action to be taken on the rows in the table that have a referential relationship when the referenced row is updated in the foreign table.

• NO ACTION (default)

The Database Engine raises an error and the update action on the row in the parent table is aborted.

• CASCADE

Corresponding rows are updated in the referencing table when that row is updated in the parent table.

• SET DEFAULT

All the values that make up the foreign key in the referencing row(s) are set to their bunt (default) values when the corresponding row in the parent foreign table is updated.

The Obelisk agent raises an error if the parent foreign table has no entry with bunt values.

Remarks

This command mutates the state of the Obelisk agent.

FOREIGN KEY constraints ensure data integrity for the data contained in the column or columns. They necessitate that each value in the column exists in the corresponding referenced column or columns in the referenced table. FOREIGN KEY constraints can only reference columns that are subject to a PRIMARY KEY or UNIQUE INDEX constraint in the referenced table.

Produced Metadata

update <database>.sys.table-columns update <database>.sys.table-columns update <database>.sys.table-ref-integrity

Exceptions

alter a column that does not exist add a column that does exist drop a column that does not exist table referenced by FOREIGN KEY does not exist table column referenced by FOREIGN KEY does not exist aura mis-match in FOREIGN KEY

ALTER TRIGGER

TBD

<alter-trigger> ::=
  ALTER TRIGGER { [ <db-qualifer> ]{ <trigger> } | ALL }
     ON { SERVER | <database.name> | <table> | <view> }
     [ ENABLE | DISABLE ]

ALTER VIEW

Alter the structure of an existing <view>.

<alter-view> ::=
  ALTER VIEW [ <db-qualifer> ]{ <view> }
    ( { [<alias>.] <column> } [ ,...n ] )
  AS <select_statement>

API

+$  alter-view
  $:
    %alter-view
    view=qualified-object
    transform
  ==

Arguments

<view> Specifies the name of the view to alter.

<transform> Refers to the <transform> producing the output <table-set>.

Remarks

This command mutates the state of the Obelisk agent.

Produced Metadata

UPDATE <database>.sys.views UPDATE <database>.sys.view-columns

Exceptions

view does not exist.