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

# vsql_complex extension for MySQL

> The vsql_complex extension adds a COMPLEX column type to MySQL with arithmetic, magnitude, and conjugate functions, and ships as a worked example of a VEF custom type.

`vsql_complex` adds a `COMPLEX` column type that stores a complex number as two
doubles, with the arithmetic to go with it. It ships inside the server as a
worked example of a custom type, and it shows what a VEF type needs end to end:
a binary layout, a text form, a comparison rule, and an aggregate.

| | |
| - | - |
| **Maintainer** | VillageSQL |
| **Source** | [villagesql-server/villagesql/examples/vsql-complex](https://github.com/villagesql/villagesql-server/tree/main/villagesql/examples/vsql-complex) |
| **License** | GPL-2.0 |

## Install

`vsql_complex` lives in the server source tree, so its bundle is present after
every install method, including a build from source. Install it into the server
with one statement:

```sql theme={null}
INSTALL EXTENSION vsql_complex;
```

Confirm it is there:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_complex';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_complex   |
+----------------+
```

## What it adds

### The COMPLEX type

A value is written `'(real,imaginary)'` and occupies 16 bytes. The bundle also
registers a `COMPLEX2` variant, which this page does not cover.

```sql theme={null}
CREATE TABLE signals (
    id        INT PRIMARY KEY,
    impedance COMPLEX
);
```

### Functions

| Function | Returns | What it does |
| - | - | - |
| `complex_add(a, b)` | `COMPLEX` | Addition |
| `complex_subtract(a, b)` | `COMPLEX` | Subtraction |
| `complex_multiply(a, b)` | `COMPLEX` | Multiplication |
| `complex_divide(a, b)` | `COMPLEX` | Division |
| `complex_real(a)` | real | The real part |
| `complex_imag(a)` | real | The imaginary part |
| `complex_abs(a)` | real | The magnitude |
| `complex_conjugate(a)` | `COMPLEX` | The conjugate |
| `complex_sum(a)` | `COMPLEX` | Aggregate: the sum across a group |

## Example

```sql theme={null}
INSERT INTO signals VALUES
    (1, '(50.0,0.0)'),
    (2, '(3.0,4.0)'),
    (3, '(0.0,-2.5)');

SELECT id, impedance,
       complex_real(impedance) AS re,
       complex_imag(impedance) AS im,
       complex_abs(impedance) AS magnitude
FROM signals;
```

```
+----+-----------+------+------+-----------+
| id | impedance | re   | im   | magnitude |
+----+-----------+------+------+-----------+
|  1 | (50,0)    |   50 |    0 |        50 |
|  2 | (3,4)     |    3 |    4 |         5 |
|  3 | (0,-2.5)  |    0 | -2.5 |       2.5 |
+----+-----------+------+------+-----------+
```

Multiplying by `(0,1)` rotates a value a quarter turn, and the aggregate adds a
whole column:

```sql theme={null}
SELECT complex_multiply(impedance, '(0,1)') AS rotated FROM signals WHERE id = 2;
SELECT complex_sum(impedance) AS total FROM signals;
```

```
+---------+
| rotated |
+---------+
| (-4,3)  |
+---------+
+----------+
| total    |
+----------+
| (53,1.5) |
+----------+
```

## See also

* [Custom types](https://villagesql.com/docs/mysql-8.4/0.0.6/custom-types.md) — how a VEF type is declared, and what the server asks of it
* [Create an extension](https://villagesql.com/docs/mysql-8.4/0.0.6/create.md) — building one of your own
* [Available extensions](https://villagesql.com/docs/mysql-8.4/0.0.6/extensions.md) — the full catalog


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.