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

# Matrix Functions and Operators

> Reference for Ocient SQL matrix functions and operators for constructing, multiplying, transposing, and inspecting matrix values used in analytics and ML.

export const OcientML = "OcientML™";

export const Ocient = "Ocient®";

In {Ocient}, a matrix is a fixed‑size, multi‑dimensional array of `DOUBLE` values. Many {OcientML} models and feature representations are naturally expressed as matrices, making them a core building block for in‑database machine learning.

Matrices help you:

* **Store dense numeric features** — Keep related numeric inputs together as a single matrix value instead of many scalar columns. This storage simplifies machine learning training and scoring queries.
* **Represent model internals and transformations** — Learned weights, intermediate layers, and linear transformations are often matrix‑shaped. Keeping these as matrices in SQL lets more of the machine learning pipeline execute directly in Ocient.
* **Apply math and linear‑algebra style operations in SQL** — Matrix functions and operators let you construct, inspect, and manipulate matrix values in the same queries that drive machine learning models and preprocessing steps.

For an overview of Ocient machine-learning capabilities, see [Machine Learning in Ocient](/machine-learning-in-ocient).

## Matrix Usage

To define a matrix data type in SQL, use the syntax `MATRIX[rows][columns]`, where the bracketed numbers specify the number of matrix rows and columns.

**Example**

This example creates a basic table `matrix_example` with a matrix column `col_matrix` that contains matrices with two rows and three columns.

```sql SQL theme={null}
CREATE TABLE matrix_example (
    id INT,
    col_matrix MATRIX[2][3] NOT NULL
);
```

Insert data for two matrices into the matrix column.

```sql SQL theme={null}
INSERT INTO matrix_example (id, col_matrix) VALUES
    (1, {{1, 2, 3}, {4, 5, 6}}),
    (2, {{0, 0, 0}, {7, 8, 9}});
```

For more DDL examples that use matrices, see [CREATE TABLE SQL Statement Examples](/create-table-sql-statement-examples).

For details about working with matrix values, see [Data Types](/data-types).

## Matrix Functions

<Info>
  In the examples, `_R{}` and `_C{}` are vector notation, meaning `_R{ 1,2,3 }` is a row vector with values `1`, `2`, and `3`.
</Info>

| **Function** | **Syntax** | **Purpose** | **Example** | **Result** |
| - | - | - | - | - |
| Constructor | make\_matrix\_ixj(i, j, e\_00, …, e\_ij) | Creates an `ixj` matrix with elements `e_00`, `…`, `e_ij` | make\_matrix\_1x3(1,3,1,2,3) | \{ \{1.0,2.0,3.0} } |
| Constructor (2) | matrix\_from\_text(string) | Creates a matrix from the specified string | matrix\_from\_text('\{ \{1,2,3}, \{1,2,3} }') | \{ \{1.0,2.0,3.0}, \{1.0,2.0,3.0} } |
| + (matrix addition) | matrix + matrix | Performs matrix addition | \{ \{1,2,3}, \{4,5,6} } + \{ \{4,5,6}, \{1,2,3} } | \{ \{5.0,7.0,9.0}, \{5.0,7.0,9.0} } |
| - (matrix subtraction) | matrix - matrix | Performs matrix subtraction | \{ \{1,2,3}, \{4,5,6} } - \{ \{4,5,6}, \{1,2,3} } | \{ \{-3.0,-3.0,-3.0}, \{3.0,3.0,3.0} } |
| \* (scalar multiplication) | numeric \* matrix | Performs scalar multiplication | 2 \* \{ \{4,5,6}, \{1,2,3} } | \{ \{2.0,4.0,6.0}, \{8.0,10.0,12.0} } |
| \* (matrix multiplication) | matrix \* matrix | Performs matrix multiplication | \{ \{1,2,3}, \{4,5,6} } \* \{ \{1,2}, \{3,4}, \{5,6} } | \{ \{22.0,28.0}, \{49.0,64.0} } |
| / (scalar division) | matrix / numeric | Performs scalar division | \{ \{1,2,3}, \{4,5,6} } / 2 | \{ \{0.5,1.0,1.5}, \{2.0,2.5,3.0} } |
| transpose | transpose(matrix) | Returns the transpose of the matrix | transpose( \{ \{1,2,3}, \{4,5,6} } ) | \{ \{1.0,4.0}, \{2.0,5.0}, \{3.0,6.0} } |
| determinant | det(matrix) | Returns the determinant of the matrix as a double | det( \{ \{1,2}, \{3,4} } ) | -2.0 |
| inverse | inverse(matrix) | Returns the inverse of a square, invertible matrix | inverse( \{ \{1,2}, \{3,4} } ) | \{ \{-2.0, 1.0}, \{1.5, -0.5} } |
| trace | matrix\_trace(matrix) | Returns the trace of a square matrix as a double | matrix\_trace( \{ \{1,2,3}, \{4,5,6}, \{7,8,9} } ) | 15.0 |
| vector sum | vector\_sum(matrix) | Returns the sum of elements in a one-dimensional matrix/vector | vector\_sum( \_R{ 1,2,3 } )<br />vector\_sum( \_C{ 1,2,3 } ) | 6.0 |
| vector min | vector\_min(matrix) | Returns the minimum of elements in a one-dimensional matrix/vector | vector\_min( \_R{ 1,2,3 } )<br />vector\_min( \_C{ 1,2,3 } ) | 1.0 |
| vector max | vector\_max(matrix) | Returns the maximum of elements in a one-dimensional matrix/vector | vector\_max( \_R{ 1,2,3 } )<br />vector\_max( \_C{ 1,2,3 } ) | 3.0 |
| vector argmin | vector\_argmin(matrix) | Returns the 1-based position (index) of the minimum element in a one-dimensional matrix or vector (row or column vector). The first element has index 1. | vector\_argmin(\_R{1, -1, 5, 0}) | 2 |
| vector argmax | vector\_argmax(matrix) | Returns the 1-based position (index) of the maximum element of a one-dimensional matrix or vector. The first element has index 1. | vector\_argmax(\_C{1, -1, 5, 0}) | 3 |
| softmax | softmax(matrix) | Returns the softmax of a one-dimensional matrix or vector. | softmax(\_R{1, 1}) | \{{0.5, 0.5}} |
| cross entropy loss | cross\_entropy\_loss(matrix, matrix) | Returns the cross entropy loss of two one-dimensional matrices or vectors. | cross\_entropy\_loss( \_R{ 0.2, 0.5, 0.8 }, \_C{ 0,1,0 } )<br /><br />cross\_entropy\_loss( \_C{ 0.2, 0.5, 0.8}, \_R{ 0,1,0 } )<br /><br />cross\_entropy\_loss( \_R{ 0.2, 0.5, 0.8 }, \_R{ 0,1,0 } )<br /><br />cross\_entropy\_loss( \_C{ 0.2, 0.5, 0.8 }, \_C{ 0,1,0} ) | 0.69 |
| log loss | log\_loss(matrix, matrix) | Returns the log loss of two one-dimensional matrices or vectors. | log\_loss( \_R{ 0.2, 0.5, 0.8 }, \_C{ 0,1,0 } )<br />log\_loss( \_C{ 0.2, 0.5, 0.8}, \_R{ 0,1,0 } )<br />log\_loss( \_R{ 0.2, 0.5, 0.8 }, \_R{ 0,1,0 } )<br />log\_loss( \_C{ 0.2, 0.5, 0.8 }, \_C{ 0,1,0} ) | 2.53 |
| logits loss | logits\_loss(matrix, matrix) | Returns the logits loss of two one-dimensional matrices or vectors. | logits\_loss( \_R{ 0.2, 0.5, 0.8 }, \_C{ 0,1,0 } )<br />logits\_loss( \_C{ 0.2, 0.5, 0.8}, \_R{ 0,1,0 } )<br />logits\_loss( \_R{ 0.2, 0.5, 0.8 }, \_R{ 0,1,0 } )<br />logits\_loss( \_C{ 0.2, 0.5, 0.8 }, \_C{ 0,1,0} ) | 2.44 |
| hinge loss | hinge\_loss(matrix, matrix) | Returns the hinge loss of two one-dimensional matrices or vectors. | hinge\_loss( \_R{ 0.2, 0.5, 0.8 }, \_C{ 0,1,0 } )<br />hinge\_loss( \_C{ 0.2, 0.5, 0.8}, \_R{ 0,1,0 } )<br />hinge\_loss( \_R{ 0.2, 0.5, 0.8 }, \_R{ 0,1,0 } )<br />hinge\_loss( \_C{ 0.2, 0.5, 0.8 }, \_C{ 0,1,0} ) | 3.5 |
| dot product | dot(matrix, matrix) | Returns the dot product of two one-dimensional matrices/vectors | dot( \_R{ 1,2,3 }, \_C{ 1,2,3 } )<br />dot( \_C{ 1,2,3 }, \_R{ 1,2,3 } )<br />dot( \_R{ 1,2,3 }, \_R{ 1,2,3 } )<br />dot( \_C{ 1,2,3 }, \_C{ 1,2,3 } ) | 14.0 |
| magnitude | abs(matrix) | Returns the magnitude of one-dimensional matrix/vector | abs( \_R{ 1,2,3 } )<br />abs( \_C{ 1,2,3 } ) | 3.74 |
| LUPQ decomp | LUPQ\_decomp(matrix) | Returns LUPQ decomposition of a square matrix A as a tuple of 4 matrices where PAQ = LU | | |
| LUP decomp | LUP\_decomp(matrix) | Returns LUP decomposition of a square matrix as a tuple of 3 matrices | | |
| QR decomp | qrdecomp(matrix) | Returns QR decomposition of a matrix as a tuple of 2 matrices | | |
| SVD decomp | SVD\_decomp(matrix) | Returns SVD decomposition of a matrix as a tuple of 3 matrices | | |
| eigenvalues/vectors | eigen(matrix) | Returns eigenvalues and eigenvalues of a square matrix as a vector of pairs | | |
| identity matrix | identity\_matrix(unsigned int) | Returns an identity matrix of the specified dimension | identity\_matrix(3) | \{ \{1.0,0.0,0.0}, \{0.0,1.0,0.0}, \{0.0,0.0,1.0} } |
| NULL matrix | null\_matrix(unsigned int, unsigned int) | Returns a NULL matrix of the specified (row, col) dimensions | null\_matrix(2, 3) | NULL |
| zero matrix | zero\_matrix(unsigned int, unsigned int) | Returns a zero matrix of the specified (row, col) dimensions | zero\_matrix(2, 3) | \{ \{0.0,0.0,0.0}, \{0.0,0.0,0.0} } |
| matrix dimension | matrix\_dim(matrix) | Returns the dimensions of the specified matrix as a tuple of (row, col) integers. When the input matrix is NULL, the function returns NULL. | matrix\_dim(\_R\{1, 2, 3}) | TUPLE\<INT,INT>(1, 3) |
| Frobenius norm | frobenius(matrix) | Returns the Frobenius norm of a matrix. This norm is the matrix norm of an `M``  x  ``N` matrix defined as the square root of the sum of the absolute squares of its elements.<br />\|a\|^2 is the same as a^2, where a is a real number. | frobenius(matrix\_from\_text('\{\{3,4},\{8,6}}'))<br /> | 11.180339887498949 <br /> |

## Matrix Operators

| **Operator** | **Syntax** | **Purpose** |
| - | - | - |
| \< | matrix \< matrix | Less than comparison |
| > | matrix > matrix | Greater than comparison |
| \<= | matrix \<= matrix | Less than or equal to comparison |
| >= | matrix >= matrix | Greater than or equal to comparison |
| = | matrix = matrix | Equal to comparison |
| \<> | matrix \<> matrix | Not equal to comparison |
| \[,] | matrix\[rowIndex,colIndex] | Access the matrix at the specified row and column. 1-Indexed. Accessing a NULL matrix or using a NULL index returns NULL. Access out of bounds returns a NULL. |
| \[:,:] | matrix\[r1:c1,r2:c2] | Slice the matrix at the specified row range and column range.<br />\* The index starts at `1`.<br />\* Slicing a NULL matrix or using a NULL index returns NULL.<br />\* Start indices omitted or below `1` become `1`. End indices omitted or above the number of rows/columns become the number of rows/columns. Example — `matrix_10X10[:10,-1:20]` is equivalent to `matrix[1:10,1:10]`.<br />\* Ranges completely out of bounds throw an `INVALID_ARGUMENT` error.<br />\* Sequential slices like `matrix[1:1,1:1][1:1,1:1]` throw an error.<br />\* Slices cannot be combined with access. `matrix[1,1:10]` is not allowed, but `matrix_10X10[1:1,1:10]` is.<br />\* Trying to slice with non-constant indexes throws an error. |

### Operator Examples

| **Operator** | **SQL Predicate** | **Result** |
| - | - | - |
| `<` | `{ {1,2,3}, {4,5,6} } < { {4,5,6}, {1,2,3} }` | true |
| | `{ {1,2,3}, {4,5,6} } < { {1,2,2}, {1,2,3} }` | false |
| | `{ {1,2,3}, {4,5,6} } < { {1,2,3}, {4,5,6} }` | false |
| `>` | `{ {4,5,6}, {4,5,6} } > { {1,2,3}, {7,8,9} }` | true |
| | `{ {1,2,3}, {4,5,6} } > { {4,5,6}, {1,2,3} }` | false |
| | `{ {1,2,3}, {4,5,6} } > { {1,2,3}, {4,5,6} }` | false |
| `<=` | `{ {1,2,3}, {4,5,6} } <= { {4,5,6}, {1,2,3} }` | true |
| | `{ {1,2,3}, {4,5,6} } <= { {1,2,2}, {1,2,3} }` | false |
| | `{ {1,2,3}, {4,5,6} } <= { {1,2,3}, {4,5,6} }` | true |
| `>=` | `{ {4,5,6}, {4,5,6} } >= { {1,2,3}, {7,8,9} }` | true |
| | `{ {1,2,3}, {4,5,6} } >= { {1,5,6}, {1,2,3} }` | false |
| | `{ {1,2,3}, {4,5,6} } >= { {1,2,3}, {4,5,6} }` | true |
| `=` | `{ {1,2,3}, {4,5,6} } = { {1,2,3}, {4,5,6} }` | true |
| | `{ {1,2,3}, {4,5,6} } = { {1,2,4}, {4,5,6} }` | false |
| `<>` | `{ {1,2,3}, {4,5,6} } <> { {1,2,3}, {4,5,6} }` | false |
| | `{ {1,2,3}, {4,5,6} } <> { {1,2,4}, {4,5,6} }` | true |
| `matrix_access_operator` | `{ {1,2,3}, {4,5,6} }[1,2]` | 2.0 |
| | `{ {1,2,3}, {4,5,6} }[NULL,2]` | NULL |
| `matrix_slice_operator` | `{ {1,2,3}, {4,5,6} }[1:,2:3]` | \{ \{2.0,3.0}, \{5.0,6.0} } |
| | `{ {1,2,3}, {4,5,6} }[1:NULL,2:3]` | NULL |

## Bibliography

Golub, Gene H., and Charles F. Van Loan. *Matrix Computations*. 3rd ed, Johns Hopkins University Press, 1996.

## Related Links

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

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

[Tuple Functions and Operators](/tuple-functions-and-operators)

[Data Types](/data-types)

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

[Query Ocient](/query-ocient)