TSContainerManage function

The TSContainerManage function changes the properties of containers.

Only users with update privileges on the TSContainerTable table and the TSContainerWindowTable table can run this function.

Syntax

TSContainerManage(container_name  lvarchar, 
                  command         lvarchar);

Syntax of command

{ detach [active partitions] [before] datetime | attach [dormant partitions] [after] datetime | destroy [dormant partitions ] [before] datetime | set active [window size] [to] number | set dormant [window size] [to] number | set pool [containterpool] | set extent [container] [first] first_ext [next] next_ext | set wcontrol flag [destroy_count] [future_count] }
container_name
The name of the container. The container name must exist.
command
A command that changes the properties of the container:
detach active partitions before datetime
For rolling window containers, detaches any active partitions that are before the specified timestamp to the dormant window.

The keywords active partitipants and before are optional and do not change the command.

attach dormant partitions after datetime
For rolling window containers, attaches any dormant partitions that are after the specified timestamp into the active window. However, the maximum number of partitions in the active window is not exceeded, even if more partitions fit the timestamp criteria.

The keywords dormant partitions and after are optional and do not change the command.

destroy dormant partitions before datetime
For rolling window containers, destroys any dormant partitions that are before the specified timestamp. The partitions can contain data. Any active partitions that meet the timestamp criteria are not destroyed.

The keywords dormant partitions and before are optional and do not change the command.

set active window size to number
For rolling window containers, sets the number of partitions in the active window:
  • 0 = No size limit.
  • Positive integer = The maximum number of partitions in the active window. If you decrease the size, the number of oldest active partitions that exceed the active window size are detached to the dormant window. If you increase the size, partitions in the dormant window are not attached into the active window.

The keywords window size and to are optional and do not change the command.

set dormant window size to number
For rolling window containers, sets the number of partitions in the dormant window:
  • 0 = Default. No size limit.
  • Positive integer = The maximum number of partitions in the dormant window. If you decrease the size, the number of dormant partitions that exceed the dormant window size are destroyed.

The keywords window size and to are optional and do not change the command.

set pool containerpool
Moves the container into the specified container pool.
set pool
Removes the container from its container pool. Same as the TSContainerSetPool procedure.
set extent container first first_ext next next_ext
Sets the size, in KB, of the first and next extents for the container partition.
The keywords first and next are optional and do not change the command.
set extent first first_ext next next_ext
Sets the sizes, in KB, of the first and next extents for the partitions that contain time series elements. For rolling window containers, changes the sizes of the existing partitions in the active and dormant windows and sets the size of new partitions.
The keywords first and next are optional and do not change the command.
set wcontrol flag destroy_count future_count
The flag value is the sum of flag values that represent how many partitions are destroyed, whether active partitions can be destroyed, and whether to limit partitions for future dates. Possible values are: 0, 1, 2, 3 (1 + 2), 4, 5 (1 + 4), 6 (2 + 4), 7 (1 + 2 + 4).
  • 0 = Default. As many as necessary dormant partitions are destroyed. If the operation requires more new active partitions than the value of the active_windowsize parameter, the operation fails.
  • 1 = As many as necessary existing dormant partitions and older active partitions are destroyed. Use this setting with caution. Destroyed data cannot be recovered.
  • 2 = Dormant partitions are destroyed, but limited to the number specified by the destroy_count parameter. If the number of partitions that must be destroyed for an operation exceeds the value of the destroy_count parameter, the operation fails.
  • 4 = Partitions for future dates are limited to the number specified by the future_count parameter. If the number of partitions for future dates exceeds the value of the future_count parameter, the operation fails.
The destroy_count value is valid if the flag parameter includes the value 2:
  • 0 = Default. No dormant partitions are destroyed.
  • A positive integer = The maximum number of partitions that can be destroyed in an operation. If the number of partitions that must be destroyed for an operation exceeds the value of the destroy_count value, the operation fails.
The future_count value is valid if the window_control parameter includes the value 4:
  • 0 = Default. No limit on future partitions.
  • A positive integer = The maximum number of partitions for future dates that can be added. If the number of partitions for future dates exceeds the value of the future_count parameter, the operation fails.

Usage

For all containers, you can change the container pool and the extent sizes of the partitions. For rolling window containers, you can also change the window sizes and attach, detach, or destroy partitions.

Returns

A message that describes the result of the command.

Examples

The following examples are based on a rolling window container named readings_container that has a day interval, an active window size of 5, and a dormant window size of 10. The time series elements use a 15-minute calendar with the range from 2012-01-01 00:00:00.00000 to 2012-01-10 23:45:00.00000.

The partitions are distributed between the active and the dormant windows in the following way:

  • Partitions that are in the active window:
    • P6: elements for 2012-01-06
    • P7: elements for 2012-01-07
    • P8: elements for 2012-01-08
    • P9: elements for 2012-01-09
    • P10: elements for 2012-01-10
  • Partitions that are in the dormant window:
    • P1: elements for 2012-01-01
    • P2: elements for 2012-01-02
    • P3: elements for 2012-01-03
    • P4: elements for 2012-01-04
    • P5: elements for 2012-01-05

Example 1: Detach partitions

The following example moves partitions from the active window to the dormant window:

execute function TSContainerManage(
"readings_container",
"detach active partitions before 2012-01-08")

The following message describes the result:

detach succeeded: 2 partitions moved

The partitions are now distributed between the active and the dormant windows in the following way:

  • Partitions that are in the active window:
    • P8: elements for 2012-01-08
    • P9: elements for 2012-01-09
    • P10: elements for 2012-01-10
  • Partitions that are in the dormant window:
    • P1: elements for 2012-01-01
    • P2: elements for 2012-01-02
    • P3: elements for 2012-01-03
    • P4: elements for 2012-01-04
    • P5: elements for 2012-01-05
    • P6: elements for 2012-01-06
    • P7: elements for 2012-01-07

Partitions P6 and P7 moved into the dormant window.

Example 2: Attach partitions

The following example moves a partition from the dormant window to the active window:

execute function TSContainerManage(
"readings_container",
"attach dormant partitions after 2012-01-06")

The following message describes the result:

attach succeeded: 1 partition moved

The partitions are now distributed between the active and the dormant windows in the following way:

  • Partitions that are in the active window:
    • P7: elements for 2012-01-07
    • P8: elements for 2012-01-08
    • P9: elements for 2012-01-09
    • P10: elements for 2012-01-10
  • Partitions that are in the dormant window:
    • P1: elements for 2012-01-01
    • P2: elements for 2012-01-02
    • P3: elements for 2012-01-03
    • P4: elements for 2012-01-04
    • P5: elements for 2012-01-05
    • P6: elements for 2012-01-06

Partition P7 moved into the active window.

Example 3: Increase the active window size

The following example increases the size of the active window to 10:

execute function TSContainerManage(
"readings_container",
"set active window size to 10");

The following message describes the result:

Set active window size succeeded: 0 partitions moved

Although the active window size is larger, partitions in the dormant window are not moved back into the active window.

Example 4: Destroy partitions

The following example destroys partitions in the dormant window:

execute function TSContainerManage(
"readings_container",
"destroy dormant partitions before 2012-01-08");

The following message describes the result:

destroy succeeded: 6 partitions destroyed

The partitions are now distributed between the active and the dormant windows in the following way:

  • Partitions that are in the active window:
    • P7: elements for 2012-01-07
    • P8: elements for 2012-01-08
    • P9: elements for 2012-01-09
    • P10: elements for 2012-01-10
  • No partitions in the dormant window.

Although some of the active partitions are before 2012-01-08, they are not destroyed.

Example 5: Change the destroy behavior

The following statement changes the behavior when partitions are destroyed to allow up to seven dormant and active partitions to be destroyed in an operation:

execute function TSContainerManage('readings_container','set wcontrol 3 7');