Difference between revisions of "DbWrite"
(Enterprise->Developer) |
|||
| (4 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
[[Category:Database Functions]] | [[Category:Database Functions]] | ||
| − | |||
| − | + | The [[DbWrite]] function writes data and sends other SQL to access or modify data to an external ODBC database. | |
| − | + | ''Requires {{Analytica Developer}} or above.'' | |
| − | + | == DbWrite(connection, sql) == | |
| − | + | Connects to a data source «connection» and performs an SQL query in read-write mode. This function is identical to [[DbQuery]]() except that the SQL query is processed in read-write mode, making it possible to store data in the data source from within Analytica. If you aren't changing the data base, use [[DbQuery]] instead, to minimize the changes of making a mistake that messes up your data in the data base. | |
| − | + | In most use cases, the «sql» statement serves to change the database rather than to retrieve data, and hence, you'll usually ignore the return value. However, if you issue an SQL statement that does return a record set, then like [[DbQuery]], the result is a list that you will used to index the result set. | |
| − | == | + | == Processing multiple queries == |
| − | + | ||
| + | Some databases don't accept multiple operations (insertions, deletions, etc.) in a single query. In these cases, you can separate your queries in the same «sql» text with double semicolons (<code>;;</code>). When [[DbWrite]] (or [[DbQuery]]) sees a double semicolon, it splits the «sql» text and sends each part as a separate query, but using the same sql context. | ||
| + | |||
| + | === Parameters === | ||
| + | All parameters are the same as for [[DbQuery]]. | ||
| + | |||
| + | * «connection»: the data source that you want to query. It is either a textual connection string or a «Database connection» obtained from a previous call to [[DbConnection]]. | ||
| + | * «sql»: The SQL query text. | ||
| + | * «key»: In the case where «sql» returns a meaningful result set, use this if you want to use one of the result columns and the index row labels. Provide the column name from the result set. | ||
| + | * «datesAsText»: Set this to true if you want dates (and times and date-times) to be returned as text instead as date-time numbers. | ||
| + | |||
| + | The «key» and «datesAsText» parameters are only meaningful when «sql» returns a result set, when you should normally be using [[DbQuery]] rather than [[DbWrite]]. Sothey are rarely used for [DbWrite]]. | ||
| + | |||
| + | == Examples == | ||
| + | |||
| + | [[DbWrite]] is often used to execute SQL statements like <code>INSERT INTO</code>, <code>CREATE TABLE</code>, <code>UPDATE</code>, etc. -- statements that make changes. | ||
| + | |||
| + | :<code>[[DbWrite]]("DSN=CrmDb", "INSERT INTO CustomerTable(Name,City,State,Country) VALUES ('James L. White','Carlsbad','NM','USA')")</code> | ||
== See Also == | == See Also == | ||
* [[DbQuery]] | * [[DbQuery]] | ||
| + | * [[DbConnection]] | ||
* [[Database functions]] | * [[Database functions]] | ||
* [[Database access]] | * [[Database access]] | ||
Latest revision as of 15:41, 1 July 2025
The DbWrite function writes data and sends other SQL to access or modify data to an external ODBC database.
Requires Analytica Enterprise or above.
DbWrite(connection, sql)
Connects to a data source «connection» and performs an SQL query in read-write mode. This function is identical to DbQuery() except that the SQL query is processed in read-write mode, making it possible to store data in the data source from within Analytica. If you aren't changing the data base, use DbQuery instead, to minimize the changes of making a mistake that messes up your data in the data base.
In most use cases, the «sql» statement serves to change the database rather than to retrieve data, and hence, you'll usually ignore the return value. However, if you issue an SQL statement that does return a record set, then like DbQuery, the result is a list that you will used to index the result set.
Processing multiple queries
Some databases don't accept multiple operations (insertions, deletions, etc.) in a single query. In these cases, you can separate your queries in the same «sql» text with double semicolons (;;). When DbWrite (or DbQuery) sees a double semicolon, it splits the «sql» text and sends each part as a separate query, but using the same sql context.
Parameters
All parameters are the same as for DbQuery.
- «connection»: the data source that you want to query. It is either a textual connection string or a «Database connection» obtained from a previous call to DbConnection.
- «sql»: The SQL query text.
- «key»: In the case where «sql» returns a meaningful result set, use this if you want to use one of the result columns and the index row labels. Provide the column name from the result set.
- «datesAsText»: Set this to true if you want dates (and times and date-times) to be returned as text instead as date-time numbers.
The «key» and «datesAsText» parameters are only meaningful when «sql» returns a result set, when you should normally be using DbQuery rather than DbWrite. Sothey are rarely used for [DbWrite]].
Examples
DbWrite is often used to execute SQL statements like INSERT INTO, CREATE TABLE, UPDATE, etc. -- statements that make changes.
DbWrite("DSN=CrmDb", "INSERT INTO CustomerTable(Name,City,State,Country) VALUES ('James L. White','Carlsbad','NM','USA')")
Enable comment auto-refresher