begriffs open source - ai-pg/blob - full-docs/man3/dblink_get_result.3

   1 '\" t
   2 .\"     Title: dblink_get_result
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "DBLINK_GET_RESULT" "3" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 dblink_get_result \- gets an async query result
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 dblink_get_result(text connname [, bool fail_on_error]) returns setof record
  36 .fi
  37 .SH "DESCRIPTION"
  38 .PP
  39 \fBdblink_get_result\fR
  40 collects the results of an asynchronous query previously sent with
  41 \fBdblink_send_query\fR\&. If the query is not already completed,
  42 \fBdblink_get_result\fR
  43 will wait until it is\&.
  44 .SH "ARGUMENTS"
  45 .PP
  46 \fIconnname\fR
  47 .RS 4
  48 Name of the connection to use\&.
  49 .RE
  50 .PP
  51 \fIfail_on_error\fR
  52 .RS 4
  53 If true (the default when omitted) then an error thrown on the remote side of the connection causes an error to also be thrown locally\&. If false, the remote error is locally reported as a NOTICE, and the function returns no rows\&.
  54 .RE
  55 .SH "RETURN VALUE"
  56 .PP
  57 For an async query (that is, an SQL statement returning rows), the function returns the row(s) produced by the query\&. To use this function, you will need to specify the expected set of columns, as previously discussed for
  58 \fBdblink\fR\&.
  59 .PP
  60 For an async command (that is, an SQL statement not returning rows), the function returns a single row with a single text column containing the command\*(Aqs status string\&. It is still necessary to specify that the result will have a single text column in the calling
  61 FROM
  62 clause\&.
  63 .SH "NOTES"
  64 .PP
  65 This function
  66 \fImust\fR
  67 be called if
  68 \fBdblink_send_query\fR
  69 returned 1\&. It must be called once for each query sent, and one additional time to obtain an empty set result, before the connection can be used again\&.
  70 .PP
  71 When using
  72 \fBdblink_send_query\fR
  73 and
  74 \fBdblink_get_result\fR,
  75 dblink
  76 fetches the entire remote query result before returning any of it to the local query processor\&. If the query returns a large number of rows, this can result in transient memory bloat in the local session\&. It may be better to open such a query as a cursor with
  77 \fBdblink_open\fR
  78 and then fetch a manageable number of rows at a time\&. Alternatively, use plain
  79 \fBdblink()\fR, which avoids memory bloat by spooling large result sets to disk\&.
  80 .SH "EXAMPLES"
  81 .sp
  82 .if n \{\
  83 .RS 4
  84 .\}
  85 .nf
  86 contrib_regression=# SELECT dblink_connect(\*(Aqdtest1\*(Aq, \*(Aqdbname=contrib_regression\*(Aq);
  87  dblink_connect
  88 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  89  OK
  90 (1 row)
  91
  92 contrib_regression=# SELECT * FROM
  93 contrib_regression\-# dblink_send_query(\*(Aqdtest1\*(Aq, \*(Aqselect * from foo where f1 < 3\*(Aq) AS t1;
  94  t1
  95 \-\-\-\-
  96   1
  97 (1 row)
  98
  99 contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]);
 100  f1 | f2 |     f3
 101 \-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-
 102   0 | a  | {a0,b0,c0}
 103   1 | b  | {a1,b1,c1}
 104   2 | c  | {a2,b2,c2}
 105 (3 rows)
 106
 107 contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]);
 108  f1 | f2 | f3
 109 \-\-\-\-+\-\-\-\-+\-\-\-\-
 110 (0 rows)
 111
 112 contrib_regression=# SELECT * FROM
 113 contrib_regression\-# dblink_send_query(\*(Aqdtest1\*(Aq, \*(Aqselect * from foo where f1 < 3; select * from foo where f1 > 6\*(Aq) AS t1;
 114  t1
 115 \-\-\-\-
 116   1
 117 (1 row)
 118
 119 contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]);
 120  f1 | f2 |     f3
 121 \-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-
 122   0 | a  | {a0,b0,c0}
 123   1 | b  | {a1,b1,c1}
 124   2 | c  | {a2,b2,c2}
 125 (3 rows)
 126
 127 contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]);
 128  f1 | f2 |      f3
 129 \-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 130   7 | h  | {a7,b7,c7}
 131   8 | i  | {a8,b8,c8}
 132   9 | j  | {a9,b9,c9}
 133  10 | k  | {a10,b10,c10}
 134 (4 rows)
 135
 136 contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]);
 137  f1 | f2 | f3
 138 \-\-\-\-+\-\-\-\-+\-\-\-\-
 139 (0 rows)
 140 .fi
 141 .if n \{\
 142 .RE
 143 .\}