> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tuple Functions and Operators

## Tuple Functions

| **Function**            | **Syntax**                                      | **Purpose**                                                                                                                       |
| ----------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Constructor             | tuple\<\<TYPE1,TYPE2, …, TYPEn>>(e1, e2, …, en) | Construct a tuple given elements. NULL is also supported as an element.                                                           |
| Implicit Constructor    | tuple(e1, e2, …, en)                            | Construct a tuple with the specified elements. Types of the tuple are inferred from the inner elements.                           |
| convert tuple to string | char(tuple)                                     | Converts a tuple to its string representation.                                                                                    |
| convert string to tuple | string\_to\_tuple(str, format)                  | Converts the string representation of a tuple (e.g., 'tuple\<\<INT,BIGINT,CHAR>>(1,2,NULL)') into a tuple.                        |
| tuple casting           | cast\_to\_tuple(tuple, format)                  | Converts a tuple into another tuple of a different type (e.g., cast\_to\_tuple(tuple\<\<int,int>>(1,2), 'TUPLE(BIGINT,DOUBLE)')). |

### Tuple Function Examples

| **Function**                         | **SQL statement**                                                                                  | **Result**                                         |
| ------------------------------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| type constructor                     | tuple\<\<INT,BIGINT>>(1,2)                                                                         | tuple holding INT(1) and BIGINT(2)                 |
| type constructor for array of tuples | tuple\<\<INT,BIGINT>>\[]\(tuple\<\<INT,BIGINT>>(1,2), tuple\<\<INT,BIGINT>>(3,4))                  | array holding 2 tuples: \[(1,2), (1,2)]            |
| char(\<tuple value>)                 | char(tuple\<\<INT,BIGINT>>(1,2))                                                                   | 'tuple\<\<INT,BIGINT>>(1,2)'                       |
| string\_to\_array                    | string\_to\_array('tuple\<\<INT,BIGINT>>\[tuple\<\<INT,BIGINT>>(1,2)]','ARRAY(TUPLE(INT,BIGINT))') | tuple\<\<INT,BIGINT>>\[tuple\<\<INT,BIGINT>>(1,2)] |

## Tuple Operators

| **Operator**    | **Syntax**                       | **Description**                                                                                                           |
| --------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| access operator | tuple\[element\_index]           | Returns the element stored in the specified index position. The index starts at `1`. Access out of bounds returns a NULL. |
| slice operator  | tuple\[left\_index:right\_index] | Returns the subtuple ranging from left\_index to right\_index inclusive. The index starts at `1`.                         |

### **About the Tuple Slice Operator**

* Each index starts at `1`.
* If the tuple is NULL or either index value is NULL, the result of the slicing is NULL.
* If you omit the left index, it is equivalent to using `1`. If you omit the right index, it is equivalent to `len(tuple)`. If you omit both, it returns the full tuple. `tuple<<int,int,int>>(1, 2, 3)[:]` is equivalent to `tuple<<int,int,int>>(1, 2, 3)`.
* Values below zero for the left index convert to `1`, and values beyond the tuple length for the right index convert to `len(tuple)`. `tupleVal[-1:4]` is equivalent to `tupleVal[1:4]`, and `tuple<<int,int,int>>(1, 2, 3)[1:6]` is equivalent to `tuple<<int,int,int>>(1, 2, 3)[1:3]`.
* Ranges completely out of tuple bounds throw an invalid argument error, e.g., `tuple<<int,int>>(1,2)[4:5]`.
* Sequential slices slice each dimension of tuples. `tuple<<tuple<<int,int,int>>,tuple<<int,int,int>>>>(tuple<<int,int,int>>(1, 2, 3), tuple<<int,int,int>>(4, 5, 6))[1:1][2:3]` = `tuple<<tuple<<int,int>>>>(tuple<<int,int>>(2, 3))`
* More than N sequential slices of an N-dimensional tuple, for example, three sequential slices on a two-dimensional tuple throw an error. `tuple<<int>>(1)[:][:]`
* You cannot combine slicing with the access operator. If you attempt such a combination, any access operator `[n]` converts to `[:n]`. `tupleVal[4][1:6]` = `tupleVal[:4][1:6]`.
* Slicing with non-constant indexes throws an error.
* Slicing a tuple of arrays such as `tuple<<int[],double[]>>(int[1,2,3],double[4,5,6])[1:1][2:3]` slices `[1:1]` on the tuple and `[2:3]` on the resulting inner arrays, resulting in `tuple<<int[]>>(int[2,3])`.
* Slicing a tuple with a mix of containers and primitives such as `tuple<<int,int[]>>(1,int[1,2,3])` throws an error if, at any given depth, the slice is not valid for one or more elements. Slicing the tuple with `[:][2:3]` fails because you cannot slice an integer, and the resultant tuple from `[:]` includes an integer. However, slicing with `[2:2][2:3]` returns `tuple<<int[]>>(int[2,3])` because the tuple resulting from the `[2:2]` slice contains only elements that the next slice range can slice.

### **Operator Examples**

| **Operator**    | **SQL Predicate**                              | **Result**                      |
| --------------- | ---------------------------------------------- | ------------------------------- |
| access operator | tuple\<\<CHAR,BIGINT>>('SQL',2)\[1]            | 'SQL'                           |
| access operator | tuple\<\<CHAR,BIGINT>>('SQL',2)\[2]            | NULL                            |
| slice operator  | tuple\<\<CHAR,BIGINT,BIGINT>>('SQL',1,2)\[1:2] | tuple\<\<CHAR,BIGINT>>('SQL',1) |

## Related Links

[Array Functions and Operators](/array-functions-and-operators)

[Matrix Functions and Operators](/matrix-functions-and-operators)

[Math Functions and Operators](/math-functions-and-operators)

[Data Types](/data-types)

[Data Types for Data Pipelines](/data-types-for-data-pipelines)

[Query Ocient](/query-ocient)