diff options
Diffstat (limited to 'doc/src/sgml/html/custom-scan-path.html')
| -rw-r--r-- | doc/src/sgml/html/custom-scan-path.html | 101 |
1 files changed, 101 insertions, 0 deletions
diff --git a/doc/src/sgml/html/custom-scan-path.html b/doc/src/sgml/html/custom-scan-path.html new file mode 100644 index 0000000..7e13d4e --- /dev/null +++ b/doc/src/sgml/html/custom-scan-path.html @@ -0,0 +1,101 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>61.1. Creating Custom Scan Paths</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider" /><link rel="next" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">61.1. Creating Custom Scan Paths</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><th width="60%" align="center">Chapter 61. Writing a Custom Scan Provider</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Next</a></td></tr></table><hr /></div><div class="sect1" id="CUSTOM-SCAN-PATH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">61.1. Creating Custom Scan Paths</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="custom-scan-path.html#CUSTOM-SCAN-PATH-CALLBACKS">61.1.1. Custom Scan Path Callbacks</a></span></dt></dl></div><p> + A custom scan provider will typically add paths for a base relation by + setting the following hook, which is called after the core code has + generated all the access paths it can for the relation (except for + Gather paths, which are made after this call so that they can use + partial paths added by the hook): +</p><pre class="programlisting"> +typedef void (*set_rel_pathlist_hook_type) (PlannerInfo *root, + RelOptInfo *rel, + Index rti, + RangeTblEntry *rte); +extern PGDLLIMPORT set_rel_pathlist_hook_type set_rel_pathlist_hook; +</pre><p> + </p><p> + Although this hook function can be used to examine, modify, or remove + paths generated by the core system, a custom scan provider will typically + confine itself to generating <code class="structname">CustomPath</code> objects and adding + them to <code class="literal">rel</code> using <code class="function">add_path</code>. The custom scan + provider is responsible for initializing the <code class="structname">CustomPath</code> + object, which is declared like this: +</p><pre class="programlisting"> +typedef struct CustomPath +{ + Path path; + uint32 flags; + List *custom_paths; + List *custom_private; + const CustomPathMethods *methods; +} CustomPath; +</pre><p> + </p><p> + <code class="structfield">path</code> must be initialized as for any other path, including + the row-count estimate, start and total cost, and sort ordering provided + by this path. <code class="structfield">flags</code> is a bit mask, which + specifies whether the scan provider can support certain optional + capabilities. <code class="structfield">flags</code> should include + <code class="literal">CUSTOMPATH_SUPPORT_BACKWARD_SCAN</code> if the custom path can support + a backward scan, <code class="literal">CUSTOMPATH_SUPPORT_MARK_RESTORE</code> if it + can support mark and restore, + and <code class="literal">CUSTOMPATH_SUPPORT_PROJECTION</code> if it can perform + projections. (If <code class="literal">CUSTOMPATH_SUPPORT_PROJECTION</code> is not + set, the scan node will only be asked to produce Vars of the scanned + relation; while if that flag is set, the scan node must be able to + evaluate scalar expressions over these Vars.) + An optional <code class="structfield">custom_paths</code> is a list of <code class="structname">Path</code> + nodes used by this custom-path node; these will be transformed into + <code class="structname">Plan</code> nodes by planner. + <code class="structfield">custom_private</code> can be used to store the custom path's + private data. Private data should be stored in a form that can be handled + by <code class="literal">nodeToString</code>, so that debugging routines that attempt to + print the custom path will work as designed. <code class="structfield">methods</code> must + point to a (usually statically allocated) object implementing the required + custom path methods, which are further detailed below. + </p><p> + A custom scan provider can also provide join paths. Just as for base + relations, such a path must produce the same output as would normally be + produced by the join it replaces. To do this, the join provider should + set the following hook, and then within the hook function, + create <code class="structname">CustomPath</code> path(s) for the join relation. +</p><pre class="programlisting"> +typedef void (*set_join_pathlist_hook_type) (PlannerInfo *root, + RelOptInfo *joinrel, + RelOptInfo *outerrel, + RelOptInfo *innerrel, + JoinType jointype, + JoinPathExtraData *extra); +extern PGDLLIMPORT set_join_pathlist_hook_type set_join_pathlist_hook; +</pre><p> + + This hook will be invoked repeatedly for the same join relation, with + different combinations of inner and outer relations; it is the + responsibility of the hook to minimize duplicated work. + </p><div class="sect2" id="CUSTOM-SCAN-PATH-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">61.1.1. Custom Scan Path Callbacks</h3></div></div></div><p> +</p><pre class="programlisting"> +Plan *(*PlanCustomPath) (PlannerInfo *root, + RelOptInfo *rel, + CustomPath *best_path, + List *tlist, + List *clauses, + List *custom_plans); +</pre><p> + Convert a custom path to a finished plan. The return value will generally + be a <code class="literal">CustomScan</code> object, which the callback must allocate and + initialize. See <a class="xref" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Section 61.2</a> for more details. + </p><p> +</p><pre class="programlisting"> +List *(*ReparameterizeCustomPathByChild) (PlannerInfo *root, + List *custom_private, + RelOptInfo *child_rel); +</pre><p> + This callback is called while converting a path parameterized by the + top-most parent of the given child relation <code class="literal">child_rel</code> + to be parameterized by the child relation. The callback is used to + reparameterize any paths or translate any expression nodes saved in the + given <code class="literal">custom_private</code> member of a + <code class="structname">CustomPath</code>. The callback may use + <code class="literal">reparameterize_path_by_child</code>, + <code class="literal">adjust_appendrel_attrs</code> or + <code class="literal">adjust_appendrel_attrs_multilevel</code> as required. + </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 61. Writing a Custom Scan Provider </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 61.2. Creating Custom Scan Plans</td></tr></table></div></body></html>
\ No newline at end of file |