begriffs open source - ai-pg/blob - full-docs/txt/custom-scan-path.txt

   1
   2 60.1. Creating Custom Scan Paths #
   3
   4    60.1.1. Custom Scan Path Callbacks
   5
   6    A custom scan provider will typically add paths for a base relation by
   7    setting the following hook, which is called after the core code has
   8    generated all the access paths it can for the relation (except for
   9    Gather and Gather Merge paths, which are made after this call so that
  10    they can use partial paths added by the hook):
  11 typedef void (*set_rel_pathlist_hook_type) (PlannerInfo *root,
  12                                             RelOptInfo *rel,
  13                                             Index rti,
  14                                             RangeTblEntry *rte);
  15 extern PGDLLIMPORT set_rel_pathlist_hook_type set_rel_pathlist_hook;
  16
  17    Although this hook function can be used to examine, modify, or remove
  18    paths generated by the core system, a custom scan provider will
  19    typically confine itself to generating CustomPath objects and adding
  20    them to rel using add_path, or add_partial_path if they are partial
  21    paths. The custom scan provider is responsible for initializing the
  22    CustomPath object, which is declared like this:
  23 typedef struct CustomPath
  24 {
  25     Path      path;
  26     uint32    flags;
  27     List     *custom_paths;
  28     List     *custom_restrictinfo;
  29     List     *custom_private;
  30     const CustomPathMethods *methods;
  31 } CustomPath;
  32
  33    path must be initialized as for any other path, including the row-count
  34    estimate, start and total cost, and sort ordering provided by this
  35    path. flags is a bit mask, which specifies whether the scan provider
  36    can support certain optional capabilities. flags should include
  37    CUSTOMPATH_SUPPORT_BACKWARD_SCAN if the custom path can support a
  38    backward scan, CUSTOMPATH_SUPPORT_MARK_RESTORE if it can support mark
  39    and restore, and CUSTOMPATH_SUPPORT_PROJECTION if it can perform
  40    projections. (If CUSTOMPATH_SUPPORT_PROJECTION is not set, the scan
  41    node will only be asked to produce Vars of the scanned relation; while
  42    if that flag is set, the scan node must be able to evaluate scalar
  43    expressions over these Vars.) An optional custom_paths is a list of
  44    Path nodes used by this custom-path node; these will be transformed
  45    into Plan nodes by planner. As described below, custom paths can be
  46    created for join relations as well. In such a case, custom_restrictinfo
  47    should be used to store the set of join clauses to apply to the join
  48    the custom path replaces. Otherwise it should be NIL. custom_private
  49    can be used to store the custom path's private data. Private data
  50    should be stored in a form that can be handled by nodeToString, so that
  51    debugging routines that attempt to print the custom path will work as
  52    designed. methods must point to a (usually statically allocated) object
  53    implementing the required custom path methods, which are further
  54    detailed below.
  55
  56    A custom scan provider can also provide join paths. Just as for base
  57    relations, such a path must produce the same output as would normally
  58    be produced by the join it replaces. To do this, the join provider
  59    should set the following hook, and then within the hook function,
  60    create CustomPath path(s) for the join relation.
  61 typedef void (*set_join_pathlist_hook_type) (PlannerInfo *root,
  62                                              RelOptInfo *joinrel,
  63                                              RelOptInfo *outerrel,
  64                                              RelOptInfo *innerrel,
  65                                              JoinType jointype,
  66                                              JoinPathExtraData *extra);
  67 extern PGDLLIMPORT set_join_pathlist_hook_type set_join_pathlist_hook;
  68
  69    This hook will be invoked repeatedly for the same join relation, with
  70    different combinations of inner and outer relations; it is the
  71    responsibility of the hook to minimize duplicated work.
  72
  73    Note also that the set of join clauses to apply to the join, which is
  74    passed as extra->restrictlist, varies depending on the combination of
  75    inner and outer relations. A CustomPath path generated for the joinrel
  76    must contain the set of join clauses it uses, which will be used by the
  77    planner to convert the CustomPath path into a plan, if it is selected
  78    by the planner as the best path for the joinrel.
  79
  80 60.1.1. Custom Scan Path Callbacks #
  81
  82 Plan *(*PlanCustomPath) (PlannerInfo *root,
  83                          RelOptInfo *rel,
  84                          CustomPath *best_path,
  85                          List *tlist,
  86                          List *clauses,
  87                          List *custom_plans);
  88
  89    Convert a custom path to a finished plan. The return value will
  90    generally be a CustomScan object, which the callback must allocate and
  91    initialize. See Section 60.2 for more details.
  92
  93 List *(*ReparameterizeCustomPathByChild) (PlannerInfo *root,
  94                                           List *custom_private,
  95                                           RelOptInfo *child_rel);
  96
  97    This callback is called while converting a path parameterized by the
  98    top-most parent of the given child relation child_rel to be
  99    parameterized by the child relation. The callback is used to
 100    reparameterize any paths or translate any expression nodes saved in the
 101    given custom_private member of a CustomPath. The callback may use
 102    reparameterize_path_by_child, adjust_appendrel_attrs or
 103    adjust_appendrel_attrs_multilevel as required.