15.00 - OTRIM - Teradata Database

Teradata Database SQL Functions, Operators, Expressions, and Predicates

Product
Teradata Database
Release Number
15.00
Content Type
Programming Reference
Publication ID
B035-1145-015K
Language
English (United States)

OTRIM

Purpose  

Removes one or more populated elements from the end of array_expr.

Syntax  

System function syntax:

Method-style syntax:

where:

 

Syntax element…

Specifies…

TD_SYSFNLIB

the name of the database where the method is located.

array_expr

an ARRAY expression, which is one of the following:

  • A reference to an ARRAY column
  • An ARRAY constructor expression. See “ARRAY Constructor Expression” on page 195.
  • A UDF expression
  • A UDM expression
  • integer_value

    an optional unsigned INTEGER value indicating the number of populated elements to remove from the array. The default value is 1.

    ANSI Compliance

    This is a Teradata extension to the ANSI SQL:2011 standard.

    Usage Notes  

    OTRIM takes an array expression as an argument and removes one or more populated elements from the end of the array value. If you do not specify integer_value, then OTRIM removes a single populated element from the end of the array value; otherwise, OTRIM removes the number of populated elements specified by integer_value from the end of the array value. For a multidimensional ARRAY type, this is done in row-major order. OTRIM returns a new modified copy of the array value as the result.

    If array_expr is NULL, an error is returned. If integer_value is NULL, no error occurs, but no action is taken by OTRIM. If the number of elements to be removed by OTRIM is greater than the current value of OCOUNT for the array, then an error is returned.

    The OTRIM method is compatible with the Oracle TRIM method for one-dimensional ARRAY types. If integer_value is not specified, the empty set of parentheses required by Teradata syntax is a deviation from Oracle syntax.

    Result Type

    OTRIM returns a new modified copy of the array argument.

    Example  

    Consider the following one-dimensional ARRAY data type and table.

    CREATE TYPE phonenumbers AS VARRAY(20) OF CHAR(10);
     
    CREATE TABLE employee_info (eno INTEGER, phonelist phonenumbers);

    The table is populated with the following values:

    /* The first 2 elements are populated; the rest are uninitialized. */
    INSERT INTO employee_info VALUES (1, 
       phonenumbers('1112223333', '6195551234'));
     
    /* Empty ARRAY instance */
    INSERT INTO employee_info VALUES (2, 
       phonenumbers());
     
    /* Update empty ARRAY instance such that element 3 is set to a value;
       Then elements 1 and 2 are set to NULL, the rest are uninitialized */
     
    UPDATE employee_info
    SET phonelist[3] = '8584850000'
    WHERE id = 2;

    The following query removes the last populated element from the phonelist array.

    SELECT eno, phonelist.OTRIM()
    FROM employee_info;

    The following is the result of the query.

    ENO         phonelist.OTRIM()
    ---         -----------------
     1           ('1112223333') 
     2           (NULL,NULL)

    The following query removes the last two populated elements from the phonelist array.

    SELECT eno, phonelist.OTRIM(2)
    FROM employee_info;

    The following is the result of the query.

    ENO         phonelist.OTRIM(2)
    ---         ------------------
     1           ()       (the only 2 populated elements were removed so we
                           now have an empty array value) 
     2           (NULL)

    Example  

    Consider the following 2-D ARRAY data type and table.

    CREATE TYPE shot_ary AS VARRAY(1:50)(1:50) OF INTEGER;
     
    CREATE TABLE seismic_table (
       id INTEGER,
       shots shot_ary);

    The table is populated with the following values:

    /* The first 2 elements are populated; the rest are uninitialized. */
    INSERT INTO seismic_table VALUES (1, shot_ary(11, 12));
     
    /* Empty ARRAY instance */
    INSERT INTO seismic_table VALUES (2, shot_ary());
     
    /* Update empty ARRAY instance such that element [1][3] is set to a value; Then elements [1][1] and [1][2] are set to NULL, the rest are uninitialized */
     
    UPDATE seismic_table
    SET shots[1][3] = 1133
    WHERE id = 2;

    The following query removes the last populated element from the shots array.

    SELECT id, shots.OTRIM() 
    FROM seismic_table
    WHERE id = 1;

    The following is the result of the query.

    ID          shots.OTRIM()
    --          -------------
     1           (11)

    The following query removes the last two populated elements from the shots array.

    SELECT id, shots.OTRIM(2) 
    FROM seismic_table;

    The following is the result of the query.

    ID          shots.OTRIM(2)
    --          --------------
     1           ()   (the only 2 populated elements were removed so we now
                       have an empty array value)
     2           (NULL)

    The following is the same query using function-style syntax.

    SELECT id, OTRIM(shots, 2) 
    FROM seismic_table;