---
title: Matrix Functions and Operators
slug: lKNHmD1gmV7adMOKkm_jg
description: Use matrix functions in Ocient to handle and analyze multi-dimensional data efficiently.
docTags: 
createdAt: Thu Jul 21 2022 17:05:13 GMT+0000 (Coordinated Universal Time)
updatedAt: Fri Apr 03 2026 21:15:53 GMT+0000 (Coordinated Universal Time)
---

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&#x20;**— 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&#x20;**— 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](<././Analysis in Ocient/Machine Learning in Ocient.md>).

## 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.&#x20;

**Example**

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

```sql
CREATE TABLE matrix_example (
    id INT,
    col_matrix MATRIX[2][3] NOT NULL
);
```

Insert data for two matrices into the matrix column.

```sql
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](<././Database Administration/Schema Design/CREATE TABLE SQL Statement Examples.md>).

For details about working with matrix values, see [Data Types](<./Data Types.md>).

## Matrix Functions

:::hint{type="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`.
:::

| **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 } )&#xA;&#xA;log\_loss( \_C\{ 0.2, 0.5, 0.8}, \_R\{ 0,1,0 } )&#xA;&#xA;log\_loss( \_R\{ 0.2, 0.5, 0.8 }, \_R\{ 0,1,0 } )&#xA;&#xA;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 } )&#xA;logits\_loss( \_C\{ 0.2, 0.5, 0.8}, \_R\{ 0,1,0 } )&#xA;logits\_loss( \_R\{ 0.2, 0.5, 0.8 }, \_R\{ 0,1,0 } )&#xA;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 } )&#xA;hinge\_loss( \_C\{ 0.2, 0.5, 0.8}, \_R\{ 0,1,0 } )&#xA;hinge\_loss( \_R\{ 0.2, 0.5, 0.8 }, \_R\{ 0,1,0 } )&#xA;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                                                                                                                                                   | &#xA;                                                                                                                                                                                                                                                                              | &#xA;                                               |
| LUP decomp                 | LUP\_decomp(matrix)                       | Returns LUP decomposition of a square matrix as a tuple of 3 matrices                                                                                                                                                                     | &#xA;                                                                                                                                                                                                                                                                              | &#xA;                                               |
| QR decomp                  | qrdecomp(matrix)                          | Returns QR decomposition of a matrix as a tuple of 2 matrices                                                                                                                                                                             | &#xA;                                                                                                                                                                                                                                                                              | &#xA;                                               |
| SVD decomp                 | SVD\_decomp(matrix)                       | Returns SVD decomposition of a matrix as a tuple of 3 matrices                                                                                                                                                                            | &#xA;                                                                                                                                                                                                                                                                              | &#xA;                                               |
| eigenvalues/vectors        | eigen(matrix)                             | Returns eigenvalues and eigenvalues of a square matrix as a vector of pairs                                                                                                                                                               | &#xA;                                                                                                                                                                                                                                                                              | &#xA;                                               |
| 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`.
* 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.md>)

[Math Functions and Operators](<./Math Functions and Operators.md>)

[Tuple Functions and Operators](<./Tuple Functions and Operators.md>)

[Data Types](<./Data Types.md>)

[Data Types for Data Pipelines](<././Load Data/Data Types for Data Pipelines.md>)&#x20;

[Query Ocient](<././Query Ocient.md>)
