# Tuple

A Tuple groups a fixed number of values into one value. Each field has its own declared type. Fields can be addressed by position, and named fields can also be addressed by name.

## Syntax

```text
Tuple(T1, T2, ...)
Tuple(name1 T1, name2 T2, ...)
```

A tuple must contain at least one field. Either every field is named or every field is positional. Names must be nonempty, unique and case-sensitive.

## Creating Tuples

Construct a tuple with `tuple(...)` or provide JSON array text with exactly the declared number of fields. A named tuple also accepts a JSON object with exactly its declared field names.

Every field is converted to its declared type. Use `Nullable(T)` for a field that can contain SQL `NULL`.

## Referring to Tuple Elements

`tuple_element(value, position)` uses a positive one-based position within the declared field count. For named tuples, `tuple_element(value, 'name')` and dotted column access select the named field.

## Examples

### A positional tuple

```sql
SELECT tuple_element(CAST('[7,"Ada"]' AS Tuple(UInt32, String)), 2)
FORMAT csv;
```

```text
"Ada"
```

### Named records in a table

```sql
CREATE TABLE users(profile Tuple(id UInt64, name String));
INSERT INTO users VALUES ('{"id":7,"name":"Ada"}');
```

```sql
SELECT profile.id, profile.name,
       tuple_element(profile, 'name') AS selected_name
FROM users
FORMAT csv;
```

```text
7,"Ada","Ada"
```

### A nullable field

```sql
SELECT CAST('[7,null]' AS Tuple(UInt32, Nullable(String)))
FORMAT csv;
```

```text
"[7,null]"
```

See [Nested](https://coordinatordb.com/docs/reference/data-types/nested-data-structures) for arrays of named records and [tuple functions](https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-functions) for operations on tuple values.