Postgres-XC 1.0.3 Documentation | ||||
---|---|---|---|---|
Prev | Fast Backward | Chapter 50. Writing A Foreign Data Wrapper | Fast Forward | Next |
The FDW handler function returns a palloc'd FdwRoutine struct containing pointers to the following callback functions:
FdwPlan * PlanForeignScan (Oid foreigntableid, PlannerInfo *root, RelOptInfo *baserel);
Plan a scan on a foreign table. This is called when a query is planned.
foreigntableid is the pg_class OID of the
foreign table. root is the planner's global information
about the query, and baserel is the planner's information
about this table.
The function must return a palloc'd struct that contains cost estimates
plus any FDW-private information that is needed to execute the foreign
scan at a later time. (Note that the private information must be
represented in a form that copyObject
knows how to copy.)
The information in root and baserel can be used to reduce the amount of information that has to be fetched from the foreign table (and therefore reduce the cost estimate). baserel->baserestrictinfo is particularly interesting, as it contains restriction quals (WHERE clauses) that can be used to filter the rows to be fetched. (The FDW is not required to enforce these quals, as the finished plan will recheck them anyway.) baserel->reltargetlist can be used to determine which columns need to be fetched.
In addition to returning cost estimates, the function should update baserel->rows to be the expected number of rows returned by the scan, after accounting for the filtering done by the restriction quals. The initial value of baserel->rows is just a constant default estimate, which should be replaced if at all possible. The function may also choose to update baserel->width if it can compute a better estimate of the average result row width.
void ExplainForeignScan (ForeignScanState *node, ExplainState *es);
Print additional EXPLAIN output for a foreign table scan.
This can just return if there is no need to print anything.
Otherwise, it should call ExplainPropertyText
and
related functions to add fields to the EXPLAIN output.
The flag fields in es can be used to determine what to
print, and the state of the ForeignScanState node
can be inspected to provide runtime statistics in the EXPLAIN
ANALYZE case.
void BeginForeignScan (ForeignScanState *node, int eflags);
Begin executing a foreign scan. This is called during executor startup.
It should perform any initialization needed before the scan can start.
The ForeignScanState node has already been created, but
its fdw_state field is still NULL. Information about
the table to scan is accessible through the
ForeignScanState node (in particular, from the underlying
ForeignScan plan node, which contains a pointer to the
FdwPlan structure returned by
PlanForeignScan
).
Note that when (eflags & EXEC_FLAG_EXPLAIN_ONLY) is
true, this function should not perform any externally-visible actions;
it should only do the minimum required to make the node state valid
for ExplainForeignScan
and EndForeignScan
.
TupleTableSlot * IterateForeignScan (ForeignScanState *node);
Fetch one row from the foreign source, returning it in a tuple table slot
(the node's ScanTupleSlot should be used for this
purpose). Return NULL if no more rows are available. The tuple table
slot infrastructure allows either a physical or virtual tuple to be
returned; in most cases the latter choice is preferable from a
performance standpoint. Note that this is called in a short-lived memory
context that will be reset between invocations. Create a memory context
in BeginForeignScan
if you need longer-lived storage, or use
the es_query_cxt of the node's EState.
The rows returned must match the column signature of the foreign table being scanned. If you choose to optimize away fetching columns that are not needed, you should insert nulls in those column positions.
void ReScanForeignScan (ForeignScanState *node);
Restart the scan from the beginning. Note that any parameters the scan depends on may have changed value, so the new scan does not necessarily return exactly the same rows.
void EndForeignScan (ForeignScanState *node);
End the scan and release resources. It is normally not important to release palloc'd memory, but for example open files and connections to remote servers should be cleaned up.
The FdwRoutine and FdwPlan struct types are declared in src/include/foreign/fdwapi.h, which see for additional details.