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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="fn_ft_set_file">
<refmeta>
<refentrytitle>ft_set_file</refentrytitle>
<refmiscinfo>file</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ft_set_file</refname>
<refpurpose>associates table with tabular data structure represented by CSV document content with external CSV file.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_ft_set_file">
<funcprototype id="fproto_ft_set_file">
<funcdef>varchar <function>ft_set_file</function></funcdef>
<paramdef>in <parameter>tb</parameter> varchar</paramdef>
<paramdef>in <parameter>fname</parameter> varchar</paramdef>
<paramdef>in <parameter>delimiter</parameter> varchar</paramdef>
<paramdef><optional>in <parameter>newline</parameter> varchar (default '\n')</optional></paramdef>
<paramdef><optional>in <parameter>esc</parameter> varchar (default NULL)</optional></paramdef>
<paramdef><optional>in <parameter>skip_rows</parameter> integer (default 0)</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_ft_set_file"><title>Description</title>
<para>Associates table with tabular data structure represented by CSV document content with external CSV file.</para>
</refsect1>
<refsect1 id="params_ft_set_file"><title>Parameters</title>
<refsect2>
<title>tb</title>
<para>The name of the table that has tabular data structure represented by CSV document content.</para>
<para>Note that there is no special object type for File Tables corresponding to the tabular data structure
represented by the CSV document content. To create a File Table, a user must have DBA group privileges.
In addition, access to the referenced file is subject the same file system access functions (e.g.,
<link linkend="fn_file_to_string"><function>file_to_string</function></link> and <code>DirsAllowed</code>
INI file settings) that govern the whole Virtuoso instance.
</para>
<para>The text in each field is parsed according to the data type declared for the column whose position in
the CREATE TABLE statement corresponds to that field's position on the line. The parsing is as by the SQL
CAST function from a VARCHAR value. If the CAST fails, the line is silently ignored.
</para>
</refsect2>
<refsect2>
<title>fname</title>
<para>External CSV file name</para>
</refsect2>
<refsect2>
<title>delimiter</title>
<para>Delimiter to be used.</para>
<para>Each column in the CSV file is expected to end with the delimiter character. A field of zero length is considered
a SQL <code>NULL</code> value; i.e., if two delimiters are adjacent, the field is considered <code>NULL</code>.
Likewise, if a line begins with the delimiter, the first field is considered <code>NULL</code>.
</para>
</refsect2>
<refsect2>
<title>newline</title>
<para>Set new line encoding. By default is '\n'.</para>
</refsect2>
<refsect2>
<title>esc</title>
<para>Set escape character. By default is NULL.</para>
<para>The newline and escape characters must be single character strings. A newline or escape character following
the escape character will be added to the parsed input as a literal character, without its special interpretation.
</para>
</refsect2>
<refsect2>
<title>skip_rows</title>
<para>Use to skip n rows from the begining. By default is 0. When set to 1 for ex., treats the first row as header
and skips it. When set to 2 skips 2 rows etc.</para>
</refsect2>
</refsect1>
<refsect1 id="examples_ft_set_file">
<title>Examples</title>
<example id="ex_ft_set_file"><title>Using a Table as a Placeholder for CSV Attachment</title>
<para>In this example a SQL TABLE is created and then associated with an external CSV file.
This file is situated in a host operating system location that is accessible to the Virtuoso instance using relative
(to instance .db file) or full path file name reference (constrained by <code>DirsAllowed</code> entry in
<code>Virtuoso INI</code>).</para>
<para>CSV filename: contacts.csv (which can also be referred to as file:contacts.csv) . </para>
<para>File Content:</para>
<screen><![CDATA[
Id,Fname,Sname,Age
0,John,Smith,48
1,Anna,Clarks,62
2,Rojer,Danrette,27
3,Kate,Sigton,56
4,Tim,Craft,41
]]></screen>
<para>CSV File to SQL Table association steps:</para>
<orderedlist>
<listitem>CREATE an empty TABLE , using the SQL command:
<screen><![CDATA[
CREATE TABLE csv.tutorial.contacts
(
Id INTEGER NOT NULL,
Fname VARCHAR(20),
Sname VARCHAR(20),
Age INTEGER,
CONSTRAINT demo_table_pk PRIMARY KEY (Id)
);
]]></screen>
<orderedlist>
<listitem>Notes:
<orderedlist>
<listitem>There is no special object type for File Tables corresponding to the tabular data structure
represented by the CSV document content;</listitem>
<listitem>To create a File Table, a user must have DBA group privileges. In addition, access to the
referenced file is subject the same file system access functions (e.g., file_to_string and DirsAllowed INI
file settings) that govern the whole Virtuoso instance.</listitem>
</orderedlist>
</listitem>
</orderedlist>
</listitem>
<listitem>Use Virtuoso <link linkend="fn_ft_set_file"><function>ft_set_file</function></link> function to associate
the above newly created internal TABLE (first procedure argument) with the external CSV file (second procedure argument,
in the form of a file name relative to the Virtuoso instance); optional arguments may be used to specify delimiter,
newline, and escape characters, respectively:
<screen><![CDATA[
ft_set_file ('csv.tutorial.contacts', 'contacts.csv', ',', 1) ;
]]></screen>
<orderedlist>
<listitem>Notes:
<orderedlist>
<listitem>The text in each field is parsed according to the data type declared for the column whose position in the CREATE TABLE
statement corresponds to that field's position on the line. The parsing is as by the SQL CAST function from a VARCHAR value.
If the CAST fails, the line is silently ignored.</listitem>
<listitem>The newline and escape characters must be single character strings. A newline or escape character following the escape
character will be added to the parsed input as a literal character, without its special interpretation. </listitem>
<listitem>Each column in the CSV file is expected to end with the delimiter character. A field of zero length is considered a
SQL NULL value; i.e., if two delimiters are adjacent, the field is considered NULL. Likewise, if a line begins with the
delimiter, the first field is considered NULL.</listitem>
</orderedlist>
</listitem>
</orderedlist>
</listitem>
<listitem>Check the inserted data in the csv.tutorial.contacts table:
<screen><![CDATA[
SQL>SELECT * FROM csv.tutorial.contacts;
Id Fname Sname F_AGE
INTEGER NOT NULL VARCHAR VARCHAR INTEGER
______________________________________________________________________
0 John Smith 48
1 Anna Clarks 62
2 Rojer Danrette 27
3 Kate Sigton 56
4 Tim Craft 41
5 Rows. -- 15 msec.
]]></screen>
</listitem>
</orderedlist>
</example>
</refsect1>
<refsect1 id="seealso_ft_set_file">
<title>See Also</title>
<para><link linkend="sqlbulkloadoperations">File Tables</link></para>
<para><link linkend="fn_file_delete"><function>file_delete</function></link></para>
<para><link linkend="fn_ttlp"><function>DB.DBA.TTLP</function></link></para>
<para><link linkend="fn_ttlp_mt"><function>DB.DBA.TTLP_MT</function></link></para>
<para><link linkend="fn_ttlp_mt_local_file"><function>DB.DBA.TTLP_MT_LOCAL_FILE</function></link></para>
</refsect1>
</refentry>
|
