README.md
1# Query planning and execution for distributed hypertables
2
3The code in this directory deals with the planning and execution of
4queries and inserts on distributed hypertables. The code is based on
5PostgreSQL's `postgres_fdw`-- the foreign data wrapper implementation
6for querying tables on remote PostgreSQL servers. While we rely on the
7same basic foreign data wrapper (FDW) API for interfacing with the
8main PostgreSQL planner and executor, we don't consider us strictly
9bound to this interface. Therefore, the `timescaledb_fdw`
10implementation is not to be considered a regular stand-alone foreign
11data wrapper in that you can't manually create foreign tables of that
12type. Instead, the use of the FDW interface is out of necessity and is
13a transparent part of distributed hypertables.
14
15The code is roughly split along planning and execution lines, and
16various utilities:
17
18* `fdw.c`: Implements the foreign data wrapper interface (FDW). This
19 is just a thin layer that calls into other code.
20* `modify_(plan|exec).c`: Planning and execution of inserts, updates,
21 deletes. Note, however, that inserts are mainly handled by
22 `data_node_dispatch.c`, which optimizes for batched inserts on
23 distributed hypertables.
24* `scan_(plan|exec).c`: General planning and execution of remote
25 relation scans.
26* `relinfo.c`: Information about a remote relation, which is used for
27 planning distributed queries/inserts. This can be considered an
28 extension of a standard `RelOptInfo` object.
29* `estimate.c`: Code for estimating the cost of scanning distributed
30 hypertables and chunks.
31* `option.c`: Parsing and validation of options on servers, tables,
32 extension levels that are related to distributed queries and
33 inserts.
34* `deparse.c`: Code to generate remote SQL queries from query
35 plans. The generated SQL statements are sent to remote data node
36 servers.
37* `shippable.c`: Determines whether expressions in queries are
38 shippable to the remote end. Certain functions are not safe to
39 execute on a remote data node or might not exist there.
40* `data_node_scan_(plan|exec).c`: Code to turn per-chunk plans into
41 per-server plans for more efficient execution.
42* `data_node_chunk_assignment.c`: Methods to assign/schedule chunks on
43 data node servers.
44