From cea49fe82fedcf125eb99a780099eaf47a326b03 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 6 Apr 2012 16:04:10 -0400
Subject: Dept of second thoughts: improve the API for AnalyzeForeignTable.

If we make the initially-called function return the table physical-size
estimate, acquire_inherited_sample_rows will be able to use that to
allocate numbers of samples among child tables, when the day comes that
we want to support foreign tables in inheritance trees.
---
 doc/src/sgml/fdwhandler.sgml | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index 8e7525ab596..2c75b80b303 100644
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -279,15 +279,19 @@ EndForeignScan (ForeignScanState *node);
 
     <para>
 <programlisting>
-AcquireSampleRowsFunc
-AnalyzeForeignTable (Relation relation);
+bool
+AnalyzeForeignTable (Relation relation,
+                     AcquireSampleRowsFunc *func,
+                     BlockNumber *totalpages);
 </programlisting>
 
      This function is called when <xref linkend="sql-analyze"> is executed on
-     a foreign table.  If the FDW supports collecting statistics for this
-     foreign table, it should return a pointer to a function that will collect
-     sample rows from the table.  Otherwise, return <literal>NULL</>.  If the
-     FDW does not support collecting statistics for any tables, the
+     a foreign table.  If the FDW can collect statistics for this
+     foreign table, it should return <literal>true</>, and provide a pointer
+     to a function that will collect sample rows from the table in
+     <parameter>func</>, plus the estimated size of the table in pages in
+     <parameter>totalpages</>.  Otherwise, return <literal>false</>.
+     If the FDW does not support collecting statistics for any tables, the
      <function>AnalyzeForeignTable</> pointer can be set to <literal>NULL</>.
     </para>
 
@@ -298,18 +302,16 @@ int
 AcquireSampleRowsFunc (Relation relation, int elevel,
                        HeapTuple *rows, int targrows,
                        double *totalrows,
-                       double *totaldeadrows,
-                       BlockNumber *totalpages);
+                       double *totaldeadrows);
 </programlisting>
 
      A random sample of up to <parameter>targrows</> rows should be collected
      from the table and stored into the caller-provided <parameter>rows</>
      array.  The actual number of rows collected must be returned.  In
-     addition, store estimates of the total numbers of live rows, dead rows,
-     and pages in the table into the output parameters
-     <parameter>totalrows</>, <parameter>totaldeadrows</>, and
-     <parameter>totalpages</>.  These numbers will be recorded in the table's
-     <structname>pg_class</> entry for future use.
+     addition, store estimates of the total numbers of live and dead rows in
+     the table into the output parameters <parameter>totalrows</> and
+     <parameter>totaldeadrows</>.  (Set <parameter>totaldeadrows</> to zero
+     if the FDW does not have any concept of dead rows.)
     </para>
 
     <para>
-- 
cgit v1.2.3