vpruthi/doc-exports
1
0
Fork 0
forked from docs/doc-exports
Code Pull Requests Activity
doc-exports/docs/dws/dev/dws_06_0162.html
Lu, Huayi ef0ada5a59 DWS DEV 20240716 version 
Reviewed-by: Pruthi, Vineet <vineet.pruthi@t-systems.com>
Co-authored-by: Lu, Huayi <luhuayi@huawei.com>
Co-committed-by: Lu, Huayi <luhuayi@huawei.com>
2024-11-02 09:07:47 +00:00

124 lines
22 KiB
HTML
Raw Blame History

<a name="EN-US_TOPIC_0000001510282021"></a><a name="EN-US_TOPIC_0000001510282021"></a>
<h1 class="topictitle1">CREATE FOREIGN TABLE (SQL on other <span id="text365645234">GaussDB(DWS)</span>)</h1>
<div id="body1546826781595"><div class="section" id="EN-US_TOPIC_0000001510282021__s007f04685f3045e5b9f1d6663b833ba6"><h4 class="sectiontitle">Function</h4><p id="EN-US_TOPIC_0000001510282021__p14389144314437">Creates a foreign table for collaborative analysis in the current database. The foreign table is used to access tables stored in other databases for collaborative analysis.</p>
<p id="EN-US_TOPIC_0000001510282021__a5539e69e61514424bc1b8b74769744e4">The foreign table is read-only. It can only be queried using <strong id="EN-US_TOPIC_0000001510282021__b1382071014512">SELECT</strong>.</p>
</div>
<div class="section" id="EN-US_TOPIC_0000001510282021__sdd0a8602c61a41339b29214e8f4e9fb5"><h4 class="sectiontitle">Syntax</h4><div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001510282021__s8c6dc4d7632b4097b35dbf14ec234dec"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span>
<span class="normal">7</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">CREATE</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="k">IF</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">EXISTS</span><span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="k">table_name</span>
<span class="p">(</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="k">column_name</span><span class="w"> </span><span class="n">type_name</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="k">LIKE</span><span class="w"> </span><span class="n">source_table</span><span class="w"> </span><span class="err">}</span><span class="w"> </span><span class="p">[,</span><span class="w"> </span><span class="p">...]</span><span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">)</span>
<span class="n">SERVER</span><span class="w"> </span><span class="k">server_name</span>
<span class="k">OPTIONS</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="n">option_name</span><span class="w"> </span><span class="s1">' value '</span><span class="w"> </span><span class="err">}</span><span class="w"> </span><span class="p">[,</span><span class="w"> </span><span class="p">...]</span><span class="w"> </span><span class="p">)</span>
<span class="p">[</span><span class="w"> </span><span class="k">READ</span><span class="w"> </span><span class="k">ONLY</span><span class="w"> </span><span class="p">]</span>
<span class="p">[</span><span class="w"> </span><span class="n">DISTRIBUTE</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="err">{</span><span class="n">ROUNDROBIN</span><span class="err">}</span><span class="w"> </span><span class="p">]</span>
<span class="p">[</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="k">GROUP</span><span class="w"> </span><span class="n">groupname</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">NODE</span><span class="w"> </span><span class="p">(</span><span class="w"> </span><span class="n">nodename</span><span class="w"> </span><span class="p">[,</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="err">}</span><span class="w"> </span><span class="p">];</span>
</pre></div></td></tr></table></div>
</div>
</div>
<div class="section" id="EN-US_TOPIC_0000001510282021__section1444711503114"><h4 class="sectiontitle">Parameter Description</h4><ul id="EN-US_TOPIC_0000001510282021__ul546185021119"><li id="EN-US_TOPIC_0000001510282021__l4d281c90f2c24d5bb115a5c4c72678ef"><strong id="EN-US_TOPIC_0000001510282021__adaf7361d9a404b8ba23a7b2c8763d92a">IF NOT EXISTS</strong><p id="EN-US_TOPIC_0000001510282021__aa0b742fb82974ebcb3be3ca5e6e7da9e">Does not throw an error if a table with the same name exists. A notice is issued in this case.</p>
</li></ul>
<ul id="EN-US_TOPIC_0000001510282021__ul197416285814"><li id="EN-US_TOPIC_0000001510282021__l1ea8d0de6a4b4022a4fa2edf217c91be"><strong id="EN-US_TOPIC_0000001510282021__adeb14dc538584f259d8f972d407b3d64">table_name</strong><p id="EN-US_TOPIC_0000001510282021__a30489e2afb9040c2842b5c98e5d73e06">Specifies the name of the foreign table to be created.</p>
<p id="EN-US_TOPIC_0000001510282021__ae253f876725d443ba12939a7634dc9f5">Value range: a string. It must comply with the naming convention.</p>
</li><li id="EN-US_TOPIC_0000001510282021__la062b05736744795aabaab2df2968a1d"><strong id="EN-US_TOPIC_0000001510282021__ac5a44e2804e340548d22494b1981446b">column_name</strong><p id="EN-US_TOPIC_0000001510282021__ae7401cc4f68d41b1a557a3125a45abb7">Specifies the name of a column in the foreign table. Columns are separated by commas (,).</p>
<p id="EN-US_TOPIC_0000001510282021__a58d44cce71c74df49aa96b4fbd0998d4">Value range: a string. It must comply with the naming convention.</p>
<div class="note" id="EN-US_TOPIC_0000001510282021__nf73ab7d7e4b240ef9be2f40085fb4723"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="EN-US_TOPIC_0000001510282021__p125196733715">Constraints or indexes cannot be created on columns.</p>
</div></div>
</li><li id="EN-US_TOPIC_0000001510282021__l3c272b5daca340c1808defda982e7547"><strong id="EN-US_TOPIC_0000001510282021__a1aeb896fdb8b40fe9e69ddb9b8e37f03">type_name</strong><p id="EN-US_TOPIC_0000001510282021__ad21c43f88e02463e96357fe005c391ad">Specifies the data type of the column.</p>
<div class="note" id="EN-US_TOPIC_0000001510282021__note6609113717320"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="EN-US_TOPIC_0000001510282021__p6930138113713">Sequence and custom types are not allowed.</p>
</div></div>
</li><li id="EN-US_TOPIC_0000001510282021__l024c7c57b0664dc181cfd555eea33404"><strong id="EN-US_TOPIC_0000001510282021__a684e2a6fda5f4971a3f9b26e7f591cc8">SERVER </strong>server_name<p id="EN-US_TOPIC_0000001510282021__a3e9ecd8f567142828481ab3755298d66">Specifies the server name, which is user-definable.</p>
<p id="EN-US_TOPIC_0000001510282021__a652108c361fe453ba6b1023f451fb7c0">Value range: a string indicating an existing server. It must comply with the naming convention.</p>
</li><li id="EN-US_TOPIC_0000001510282021__li20951161316014"><strong id="EN-US_TOPIC_0000001510282021__b5952171319019">OPTIONS ( { option_name ' value ' } [, ...] )</strong><p id="EN-US_TOPIC_0000001510282021__p1795213131708">Specifies the following parameters for a foreign table:</p>
<ul id="EN-US_TOPIC_0000001510282021__ul995218135011"><li id="EN-US_TOPIC_0000001510282021__li79528135010"><strong id="EN-US_TOPIC_0000001510282021__b32467151407">table_name</strong>: table name of the associated cluster. If it is omitted, the foreign table name will be used.</li><li id="EN-US_TOPIC_0000001510282021__li2095513131101"><strong id="EN-US_TOPIC_0000001510282021__b4620612107">schema_name</strong>: schema of the associated cluster. If it is omitted, the schema of the foreign table will be used.</li><li id="EN-US_TOPIC_0000001510282021__li8970103411112"><strong id="EN-US_TOPIC_0000001510282021__b13442519123913">encoding</strong>: encoding set of the associated cluster. If it is omitted, the database encoding set of the associated cluster will be used.</li><li id="EN-US_TOPIC_0000001510282021__li171526564288"><strong id="EN-US_TOPIC_0000001510282021__b124351331122">dataencoding</strong>: used to synchronize GBK data and UTF8 data between two latin1 databases during GDS interconnection. This parameter is supported by version 8.2.0 or later clusters.<p id="EN-US_TOPIC_0000001510282021__p65201572284">When this parameter is set, <strong id="EN-US_TOPIC_0000001510282021__b144441281178">encoding</strong> indicates the actual encoding of data in the remote cluster, and <strong id="EN-US_TOPIC_0000001510282021__b18849543161720">dataencoding</strong> indicates the actual encoding of data in the local cluster.</p>
</li></ul>
<div class="note" id="EN-US_TOPIC_0000001510282021__note212414913306"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="EN-US_TOPIC_0000001510282021__p1412415493301">Assume that the database in the local cluster is <strong id="EN-US_TOPIC_0000001510282021__b1459714412920">latin1_local_db</strong> and that in the remote cluster is <strong id="EN-US_TOPIC_0000001510282021__b859714114915">latin1_remote_db</strong>, and <strong id="EN-US_TOPIC_0000001510282021__b85986415920">latin1_remote_db</strong> stores GBK data. When migrating GBK data from <strong id="EN-US_TOPIC_0000001510282021__b75989411097">latin1_remote_db</strong> to <strong id="EN-US_TOPIC_0000001510282021__b15598134119919">latin1_local_db</strong> in UTF8 encoding, you need to set the foreign table parameters <strong id="EN-US_TOPIC_0000001510282021__b1759819411999">dataencoding</strong> to U<strong id="EN-US_TOPIC_0000001510282021__b155985411299">TF8</strong> and <strong id="EN-US_TOPIC_0000001510282021__b659814112916">encoding</strong> to <strong id="EN-US_TOPIC_0000001510282021__b12599341594">GBK</strong> in the local cluster.</p>
</div></div>
</li><li id="EN-US_TOPIC_0000001510282021__li593891712477">gds_compress<p id="EN-US_TOPIC_0000001510282021__p71401452506"><a name="EN-US_TOPIC_0000001510282021__li593891712477"></a><a name="li593891712477"></a>To reduce the network transmission bandwidth, GDS interconnection provides this parameter for compression. Currently, this parameter can only be set to <strong id="EN-US_TOPIC_0000001510282021__b46541737123312">snappy</strong>. By default, data is not compressed. This parameter is supported by version 8.2.0 or later clusters.</p>
<p id="EN-US_TOPIC_0000001510282021__p1922711919471">Before using this function, ensure that the versions of the local cluster, remote cluster, and GDS are the same.</p>
<div class="note" id="EN-US_TOPIC_0000001510282021__note171611389516"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="EN-US_TOPIC_0000001510282021__p7161882513"><strong id="EN-US_TOPIC_0000001510282021__b2141114694015">gds_compress</strong> is used together with <strong id="EN-US_TOPIC_0000001510282021__b450425218408">file_type</strong>. If the value of <strong id="EN-US_TOPIC_0000001510282021__b1925735744010">file_type</strong> is <strong id="EN-US_TOPIC_0000001510282021__b119491412414">interconn</strong>, GDS must be upgraded to 8.2.0 or later. Otherwise, the error message "<strong id="EN-US_TOPIC_0000001510282021__b211523112417">ERROR: un-support format</strong>" is displayed.</p>
</div></div>
</li><li id="EN-US_TOPIC_0000001510282021__l64d4b214cd4449c9a565bc1f5543e2ba"><strong id="EN-US_TOPIC_0000001510282021__ac5f5c4c49fea4b5b8388f2188de1f7a7">READ ONLY</strong><p id="EN-US_TOPIC_0000001510282021__abcb591bd18e24658b279b5b7883f2fc5">Indicates that a table is a read-only foreign table.</p>
</li><li id="EN-US_TOPIC_0000001510282021__la882da19e7814a53bcc13879e1cb9808"><strong id="EN-US_TOPIC_0000001510282021__a1a69dfd002ff443ea0593c5223b08e03">DISTRIBUTE BY ROUNDROBIN</strong><p id="EN-US_TOPIC_0000001510282021__a20498deb2c7e44c295af99382adb8156">Specifies <strong id="EN-US_TOPIC_0000001510282021__b713760207201549">ROUNDROBIN</strong> as the distribution mode for the foreign table.</p>
</li><li id="EN-US_TOPIC_0000001510282021__li234313210232"><strong id="EN-US_TOPIC_0000001510282021__ae3a58cce858a4746a33e116011f28202">TO { GROUP groupname | NODE ( nodename [, ... ] ) }</strong><p id="EN-US_TOPIC_0000001510282021__p15347732112318">Currently, <strong id="EN-US_TOPIC_0000001510282021__b84235270615293">TO GROUP</strong> cannot be used. <strong id="EN-US_TOPIC_0000001510282021__b842352706152947">TO NODE</strong> is used for internal scale-out tools.</p>
</li></ul>
</div>
<div class="section" id="EN-US_TOPIC_0000001510282021__s07885a43a93744359b82400d0a8873b3"><h4 class="sectiontitle">Examples</h4><ol id="EN-US_TOPIC_0000001510282021__ol23151363118"><li id="EN-US_TOPIC_0000001510282021__li1431516612">Create a foreign server named <strong id="EN-US_TOPIC_0000001510282021__b567353532413">server_remote</strong>. The corresponding foreign data wrapper is <strong id="EN-US_TOPIC_0000001510282021__b367483542414">GC_FDW</strong>.<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001510282021__s0211efd2605f4c1b9bc7189580006ca8"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">CREATE</span><span class="w"> </span><span class="n">SERVER</span><span class="w"> </span><span class="n">server_remote</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">DATA</span><span class="w"> </span><span class="n">WRAPPER</span><span class="w"> </span><span class="n">GC_FDW</span><span class="w"> </span><span class="k">OPTIONS</span><span class="w"> </span><span class="p">(</span><span class="n">address</span><span class="w"> </span><span class="s1">'10.10.0.100:25000,10.10.0.101:25000'</span><span class="p">,</span><span class="n">dbname</span><span class="w"> </span><span class="s1">'test'</span><span class="p">,</span><span class="w"> </span><span class="n">username</span><span class="w"> </span><span class="s1">'test'</span><span class="p">,</span><span class="w"> </span><span class="n">password</span><span class="w"> </span><span class="s1">'{password}'</span><span class="p">);</span>
</pre></div></td></tr></table></div>
</div>
<div class="note" id="EN-US_TOPIC_0000001510282021__n5f57b19875be47c2ae24286f1987e766"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><ul id="EN-US_TOPIC_0000001510282021__ul76631856154"><li id="EN-US_TOPIC_0000001510282021__li1675918423152">The IP addresses and port numbers of associated CNs are specified in <strong id="EN-US_TOPIC_0000001510282021__b155101712317">OPTIONS</strong>. You are advised to set this parameter to an LVS address or multiple CN addresses.</li></ul>
</div></div>
</li><li id="EN-US_TOPIC_0000001510282021__li197931522315">Create a foreign table named <strong id="EN-US_TOPIC_0000001510282021__b8991202717457">region</strong>.<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001510282021__sd926eb1a47c646f089d22960d0e4bfaf"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">CREATE</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="n">region</span>
<span class="p">(</span>
<span class="w"> </span><span class="n">R_REGIONKEY</span><span class="w"> </span><span class="n">INT4</span><span class="p">,</span>
<span class="w"> </span><span class="n">R_NAME</span><span class="w"> </span><span class="nb">TEXT</span><span class="p">,</span>
<span class="w"> </span><span class="n">R_COMMENT</span><span class="w"> </span><span class="nb">TEXT</span>
<span class="p">)</span>
<span class="n">SERVER</span>
<span class="w"> </span><span class="n">server_remote</span>
<span class="k">OPTIONS</span>
<span class="p">(</span>
<span class="w"> </span><span class="k">schema_name</span><span class="w"> </span><span class="s1">'test'</span><span class="p">,</span>
<span class="w"> </span><span class="k">table_name</span><span class="w"> </span><span class="s1">'region'</span><span class="p">,</span>
<span class="w"> </span><span class="k">encoding</span><span class="w"> </span><span class="s1">'gbk'</span>
<span class="p">);</span>
</pre></div></td></tr></table></div>
</div>
</li><li id="EN-US_TOPIC_0000001510282021__li196942614119">View the created <strong id="EN-US_TOPIC_0000001510282021__b3699130733459">region</strong> foreign table.<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001510282021__sb1ab13e6c6624d8b9115ccfa7a481f9e"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span></pre></div></td><td class="code"><div><pre><span></span><span class="err">\</span><span class="n">d</span><span class="o">+</span><span class="w"> </span><span class="n">region</span>
<span class="w"> </span><span class="k">Foreign</span><span class="w"> </span><span class="k">table</span><span class="w"> </span><span class="ss">&quot;public.region&quot;</span>
<span class="w"> </span><span class="k">Column</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="k">Type</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">Modifiers</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">FDW</span><span class="w"> </span><span class="k">Options</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="k">Storage</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">Stats</span><span class="w"> </span><span class="n">target</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">Description</span>
<span class="c1">-------------+---------+-----------+-------------+----------+--------------+-------------</span>
<span class="w"> </span><span class="n">r_regionkey</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="nb">integer</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">plain</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="o">|</span>
<span class="w"> </span><span class="n">r_name</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="nb">text</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">extended</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="o">|</span>
<span class="w"> </span><span class="n">r_comment</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="nb">text</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">extended</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="o">|</span>
<span class="n">Server</span><span class="p">:</span><span class="w"> </span><span class="n">server_remote</span>
<span class="n">FDW</span><span class="w"> </span><span class="k">Options</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="k">schema_name</span><span class="w"> </span><span class="s1">'test'</span><span class="p">,</span><span class="w"> </span><span class="k">table_name</span><span class="w"> </span><span class="s1">'region'</span><span class="p">,</span><span class="w"> </span><span class="k">encoding</span><span class="w"> </span><span class="s1">'gbk'</span><span class="p">)</span>
<span class="n">FDW</span><span class="w"> </span><span class="n">permission</span><span class="p">:</span><span class="w"> </span><span class="k">read</span><span class="w"> </span><span class="k">only</span>
<span class="n">Has</span><span class="w"> </span><span class="k">OIDs</span><span class="p">:</span><span class="w"> </span><span class="k">no</span>
<span class="n">Distribute</span><span class="w"> </span><span class="k">By</span><span class="p">:</span><span class="w"> </span><span class="n">ROUND</span><span class="w"> </span><span class="n">ROBIN</span>
<span class="k">Location</span><span class="w"> </span><span class="n">Nodes</span><span class="p">:</span><span class="w"> </span><span class="k">ALL</span><span class="w"> </span><span class="n">DATANODES</span>
</pre></div></td></tr></table></div>
</div>
</li></ol>
</div>
<div class="section" id="EN-US_TOPIC_0000001510282021__s0fbc2a5223194abfab6ef421286065cc"><h4 class="sectiontitle">Helpful Links</h4><p id="EN-US_TOPIC_0000001510282021__a7b4398c8c0884924933ea2c990002227"><a href="dws_06_0192.html">DROP FOREIGN TABLE</a>, <a href="dws_06_0125.html">ALTER FOREIGN TABLE (SQL on other GaussDB(DWS))</a></p>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="dws_06_0118.html">DDL Syntax</a></div>
</div>
</div>
View Git Blame Copy Permalink