> ## 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
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
In the examples, `_R{}` and `_C{}` are vector notation, meaning `_R{ 1,2,3 }` is a row vector with values `1`, `2`, and `3`.
| **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 } )
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 } )
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 } )
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 } )
cross\_entropy\_loss( \_C{ 0.2, 0.5, 0.8}, \_R{ 0,1,0 } )
cross\_entropy\_loss( \_R{ 0.2, 0.5, 0.8 }, \_R{ 0,1,0 } )
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 } )
log\_loss( \_C{ 0.2, 0.5, 0.8}, \_R{ 0,1,0 } )
log\_loss( \_R{ 0.2, 0.5, 0.8 }, \_R{ 0,1,0 } )
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 } )
logits\_loss( \_C{ 0.2, 0.5, 0.8}, \_R{ 0,1,0 } )
logits\_loss( \_R{ 0.2, 0.5, 0.8 }, \_R{ 0,1,0 } )
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 } )
hinge\_loss( \_C{ 0.2, 0.5, 0.8}, \_R{ 0,1,0 } )
hinge\_loss( \_R{ 0.2, 0.5, 0.8 }, \_R{ 0,1,0 } )
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 } )
dot( \_C{ 1,2,3 }, \_R{ 1,2,3 } )
dot( \_R{ 1,2,3 }, \_R{ 1,2,3 } )
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 } )
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\(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.
\|a\|^2 is the same as a^2, where a is a real number. | frobenius(matrix\_from\_text('\{\{3,4},\{8,6}}'))
| 11.180339887498949
|
## 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.
\* The index starts at `1`.
\* Slicing a NULL matrix or using a NULL index returns NULL.
\* 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]`.
\* Ranges completely out of bounds throw an `INVALID_ARGUMENT` error.
\* Sequential slices like `matrix[1:1,1:1][1:1,1:1]` throw an error.
\* Slices cannot be combined with access. `matrix[1,1:10]` is not allowed, but `matrix_10X10[1:1,1:10]` is.
\* 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)