vsql_complex extension for MySQL - VillageSQL Server for MySQL - Documentation

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
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:

INSTALL EXTENSION vsql_complex;

Confirm it is there:

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.

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

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:

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 — how a VEF type is declared, and what the server asks of it
Create an extension — building one of your own
Available extensions — the full catalog

⌘I