codekingpro/portable-devtools

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!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 16.3 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 <a href="#CUSTOM-SCAN-PATH" class="id_link">#</a></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>3    A custom scan provider will typically add paths for a base relation by4    setting the following hook, which is called after the core code has5    generated all the access paths it can for the relation (except for6    Gather paths, which are made after this call so that they can use7    partial paths added by the hook):8</p><pre class="programlisting">9typedef void (*set_rel_pathlist_hook_type) (PlannerInfo *root,10                                            RelOptInfo *rel,11                                            Index rti,12                                            RangeTblEntry *rte);13extern PGDLLIMPORT set_rel_pathlist_hook_type set_rel_pathlist_hook;14</pre><p>15  </p><p>16    Although this hook function can be used to examine, modify, or remove17    paths generated by the core system, a custom scan provider will typically18    confine itself to generating <code class="structname">CustomPath</code> objects and adding19    them to <code class="literal">rel</code> using <code class="function">add_path</code>.  The custom scan20    provider is responsible for initializing the <code class="structname">CustomPath</code>21    object, which is declared like this:22</p><pre class="programlisting">23typedef struct CustomPath24{25    Path      path;26    uint32    flags;27    List     *custom_paths;28    List     *custom_private;29    const CustomPathMethods *methods;30} CustomPath;31</pre><p>32  </p><p>33    <code class="structfield">path</code> must be initialized as for any other path, including34    the row-count estimate, start and total cost, and sort ordering provided35    by this path.  <code class="structfield">flags</code> is a bit mask, which36    specifies whether the scan provider can support certain optional37    capabilities.  <code class="structfield">flags</code> should include38    <code class="literal">CUSTOMPATH_SUPPORT_BACKWARD_SCAN</code> if the custom path can support39    a backward scan, <code class="literal">CUSTOMPATH_SUPPORT_MARK_RESTORE</code> if it40    can support mark and restore,41    and <code class="literal">CUSTOMPATH_SUPPORT_PROJECTION</code> if it can perform42    projections.  (If <code class="literal">CUSTOMPATH_SUPPORT_PROJECTION</code> is not43    set, the scan node will only be asked to produce Vars of the scanned44    relation; while if that flag is set, the scan node must be able to45    evaluate scalar expressions over these Vars.)46    An optional <code class="structfield">custom_paths</code> is a list of <code class="structname">Path</code>47    nodes used by this custom-path node; these will be transformed into48    <code class="structname">Plan</code> nodes by planner.49    <code class="structfield">custom_private</code> can be used to store the custom path's50    private data.  Private data should be stored in a form that can be handled51    by <code class="literal">nodeToString</code>, so that debugging routines that attempt to52    print the custom path will work as designed.  <code class="structfield">methods</code> must53    point to a (usually statically allocated) object implementing the required54    custom path methods, which are further detailed below.55  </p><p>56   A custom scan provider can also provide join paths.  Just as for base57   relations, such a path must produce the same output as would normally be58   produced by the join it replaces.  To do this, the join provider should59   set the following hook, and then within the hook function,60   create <code class="structname">CustomPath</code> path(s) for the join relation.61</p><pre class="programlisting">62typedef void (*set_join_pathlist_hook_type) (PlannerInfo *root,63                                             RelOptInfo *joinrel,64                                             RelOptInfo *outerrel,65                                             RelOptInfo *innerrel,66                                             JoinType jointype,67                                             JoinPathExtraData *extra);68extern PGDLLIMPORT set_join_pathlist_hook_type set_join_pathlist_hook;69</pre><p>70 71   This hook will be invoked repeatedly for the same join relation, with72   different combinations of inner and outer relations; it is the73   responsibility of the hook to minimize duplicated work.74  </p><div class="sect2" id="CUSTOM-SCAN-PATH-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">61.1.1. Custom Scan Path Callbacks <a href="#CUSTOM-SCAN-PATH-CALLBACKS" class="id_link">#</a></h3></div></div></div><p>75</p><pre class="programlisting">76Plan *(*PlanCustomPath) (PlannerInfo *root,77                         RelOptInfo *rel,78                         CustomPath *best_path,79                         List *tlist,80                         List *clauses,81                         List *custom_plans);82</pre><p>83    Convert a custom path to a finished plan.  The return value will generally84    be a <code class="literal">CustomScan</code> object, which the callback must allocate and85    initialize.  See <a class="xref" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Section 61.2</a> for more details.86   </p><p>87</p><pre class="programlisting">88List *(*ReparameterizeCustomPathByChild) (PlannerInfo *root,89                                          List *custom_private,90                                          RelOptInfo *child_rel);91</pre><p>92    This callback is called while converting a path parameterized by the93    top-most parent of the given child relation <code class="literal">child_rel</code>94    to be parameterized by the child relation.  The callback is used to95    reparameterize any paths or translate any expression nodes saved in the96    given <code class="literal">custom_private</code> member of a97    <code class="structname">CustomPath</code>.  The callback may use98    <code class="literal">reparameterize_path_by_child</code>,99    <code class="literal">adjust_appendrel_attrs</code> or100    <code class="literal">adjust_appendrel_attrs_multilevel</code> as required.101   </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 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 61.2. Creating Custom Scan Plans</td></tr></table></div></body></html>