> ## 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](/docs/mysql-9.7/dev/custom-types) — how a VEF type is declared, and what the server asks of it
* [Create an extension](/docs/mysql-9.7/dev/create) — building one of your own
* [Available extensions](/docs/mysql-9.7/dev/extensions) — the full catalog