sql_import Function

Syntax

Arguments

connectionStringCharacter

The connection string (either a named or explicit connection string. If named, the ::name:: prefix is optional)

tableNameCharacter

The name of the table into which you want to import data.

tableOwnerCharacter

The owner of the table into which you want to import data.

dataCharacter

The data to be imported. Can be a CSV (comma separated value) or JSON formatted text or an Excel (.xsl, .xslx) file. See examples below.

replicateIdentityLogical

Default = .f.. Should only be set to .t. if you are importing into an empty table. If .t. then values for the auto-increment primary key (if any) that are supplied in the input data are explicitly set in the target table.

fieldMapCharacter

Default = "". If the columns in the input data do not match the field names in the target SQL table you can specify a map. The map is a crlf delimited string of field pairs. See example below.

actionCharacter

Default = "insert". The action to perform. Can be insert or upsert. Upsert will update existing records in the target table.

primaryKeyCharacter

Default = "". The primary key for the table. If the field name of the primary key in the input data does not match the field name of the primary key in the table, enter the primary key as follows: "fieldNameInData=fieldNameInTable".

Returns

resultPointer

Returns an object with these properties:

hasErrorLogical

If .t., an error occurred. Otherwise .f..

errorTextCharacter

The description of the error if an error occurred.

recordsImportedNumeric

A count of the number of records imported.

Description

Imports CSV or JSON data into an existing SQL table.

Discussion

The sql_import() function is a helper function that imports CSV or JSON data into a SQL table.

Example: fieldMap

Assume that the input data is as follows

fname,lname
fred,smith
john,jones

Assume that the target table has column names of firstName and lastName.

You would need to specify the following fieldMap:

fname=firstName
lname=lastName

Example:

dim cs as c
cs = "mydata"
tablename = "table1"
data = <<%str%
id,name,notes,dob,number
1,"Jones, Amy","Here are some notes",1992-12-18,34.56
%str%

'replicateIdentity = .f.
map = "name=fullname"

dim p as p
p = sql_import(cs,tablename,"", data,replicateIdentity,map)

? p.hasError
= .f.

Example: Import Excel File

' the "::Name::" prefix is optional.
' cs = "conn" is the same as writing cs = "::Name::conn"
dim cs as c = "conn"
dim tablename as c = "Customers2"
dim data as c = "C:\path\to\sampleExcelData.xlsx"

dim result as p
p = sql_import(cs,tablename,"",data)

? p
= errorText = ""
hasError = .F.

Example: Import JSON

JSON can also be imported into a SQL table using the sql_import() function. The JSON fields must match the column names in the table.

In the example below, JSON is inserted into a MySQL table called "roles":

dim json as c =<<%json%
[
	{"first":"Juliet","last":"Adams"},
	{"first":"Tom","last":"Jones"},
	{"first":"Betty","last":"Smith"},
	{"first":"Pete","last":"Marshall"},
	{"first":"Victoria","last":"Winslow"},
	{"first":"Daniel","last":"Brown"}
]
%json%

? sql_import("::Name::conn","roles","",json)
= errorText = ""
hasError = .F.
recordsImported = 6

? sql_records_get("::Name::conn","SELECT * from roles","","")
= 1|Juliet|Adams|
2|Tom|Jones|
3|Betty|Smith|
4|Pete|Marshall|
5|Victoria|Winslow|
6|Daniel|Brown|

If the JSON field names do not match, a mapping can be specified that defines how to map the JSON data to the table columns:

dim json2 as c =<<%json%
[
	{"firstname":"Yvette","lastname":"Eve","main_role":"CEO"},
	{"firstname":"Earl","lastname":"Grey","main_role":"Staff"}
]
%json%

dim map as c =<<%txt%
firstname=first
lastname=last
main_role=role
%txt%

? sql_import("::Name::conn","roles","",json2,.f.,map)
= errorText = ""
hasError = .F.
recordsImported = 2

? sql_records_get("::Name::conn","SELECT * FROM roles WHERE ID > 6","","")
= 7|Yvette|Eve|CEO
8|Earl|Grey|Staff

The MySQL statement to create the "roles" table is below:

CREATE TABLE 'roles' (
  'id' int(11) NOT NULL AUTO_INCREMENT,
  'first' varchar(60) NOT NULL,
  'last' varchar(60) NOT NULL,
  'role' varchar(45),
  PRIMARY KEY ('id')
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;

Upserting

An 'upsert' performs an update on existing records and an insert if there is no existing record. This is useful in situations where data being imported should be merged with existing data in a table -- rather than added as new records. The example below performs an upsert on table1 in a SQL database. The records are imported from an excel file, "c:/data/dattoimport.xlsx".

dim conn as c = "::name::myconnstr"
dim table as c = "table1"
dim file as c = "c:\data\datatoimport.xlsx"
dim action as c = "upsert"
dim primaryKey as c = "id"
dim result as p

result = sql_import(conn, table, "", file, .f., "", action, primaryKey)