# Indexes

## Spherical index

pgSphere uses `GiST` and Block Range INdexing (`BRIN`) algorithms to create spherical indices. `GiST` indexes utilize an R-tree implementation for spherical objects, while `BRIN` indexes are based on the "summarization" of data blocks (`pages`) on physical storage in order to organize data searches on ranges of summarized data that can be easily skipped on the base of search filters (see PostgreSQL documentation for further details on BRIN indexes). As a consequence, BRIN indexes are very small indexes (up to 1000 times smaller than GiST ones), generally with lower performance compared with a GiST one, but up to 100 times faster than a full sequential scan of a table performed without any index. So BRIN indexes are particularly suitable in a big data context. An index speeds up the execution time of searches based on operators `<@`, `@`, `&&`, `#`, `=`, and `!=`.

You can create a GiST index with the following spherical data types:

- point (`spoint`)

- circle (`scircle`)

- line (`sline`)

- ellipse (`sellipse`)

- polygon (`spoly`)

- path (`spath`)

- coordinates range (`sbox`)

A GiST index can be also used for quickly finding the points closest to the given one when ordering by an expression with the `<->` operator, as shown in an example below.

BRIN indexing supports just spherical points (`spoint`) and spherical coordinates range (`sbox`) at the moment.

### Simple index of spherical points

    CREATE TABLE test (
      pos spoint NOT NULL
    );
    -- Put in data now
    CREATE INDEX test_pos_idx ON test USING GIST (pos);
    VACUUM ANALYZE test;

To find the points closest to a given spherical position, use the `<->` operator:

    SELECT * FROM test ORDER BY pos <-> spoint (0.2, 0.3) LIMIT 10

BRIN index can be created through the following syntax:

    CREATE INDEX test_pos_idx USING BRIN ON test (pos);

By default, BRIN indexes summarize blocks of 128 pages. The smaller the number of pages specified, the higher the granularity in searches, and the gap in performance between GiST indexes and BRIN indexes will be decreased. Note that the size of the BRIN indexes increases as well. Different summarizations can be specified with the following command:

    CREATE INDEX test_pos_idx USING BRIN ON test (pos) WITH (pages_per_range = 16);

## `smoc` index

pgSphere uses `GIN` to create smoc indices. An index speeds up the execution time of operators `<@`, `@>`, `&&`, `=`, and `<>`.

The index works by casting all contained smocs to a fixed level, and for each pixel at that level, storing which smocs overlap with that pixel. This is especially beneficial for "overlaps" queries using the `&&` operator. The downside of that approach is that storing large smocs like "all sky" (`0/0-11`) produces a large number of index entries.

The default opclass `smoc_gin_ops` defaults to working on level 5 with a resolution of 12288 pixels (12 * 4^5). An alternative granularity can be selected by setting the `order` parameter on the opclass (integer value between 0 and 12; option only available on PG 13 and later). The alternative `smoc_gin_ops_fine` opclass works on level 8 with 786432 pixels.

### Index of smoc coverage objects

    CREATE TABLE ivoa (
      coverage smoc NOT NULL
    );
    -- Put in data now
    -- Create index with the defaut smoc_gin_ops opclass (order 5)
    CREATE INDEX ON ivoa USING GIN (coverage);
    -- Alternative index with more detail on order 7
    CREATE INDEX ivoa_order_7_idx ON ivoa USING GIN (coverage smoc_gin_ops (order = 7));
    -- Alternative operator class with fixed order 8
    CREATE INDEX ivoa_fine_idx ON ivoa USING GIN (coverage smoc_gin_ops_fine);

## Hash index

Values of type `spoint` can be indexed using a `HASH` index, supporting the `=` operator. The `spoint_hash_ops` operator class also enables `DISTINCT` queries on `spoint`.

### Hash index of spoints

    CREATE TABLE sky (
      star spoint
    );
    CREATE INDEX ON sky USING HASH (star);

    SELECT DISTINCT star FROM sky;