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