+
+
+
+
+
+
+
+
diff --git a/docs/articles/index.html b/docs/articles/index.html
new file mode 100644
index 00000000..768a200b
--- /dev/null
+++ b/docs/articles/index.html
@@ -0,0 +1,106 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Using SqlRender
+Martijn J. Schuemie
+ +2017-06-09
+
+
+
+
+
++SQL parameterization
+One of the main functions of the package is to support parameterization of SQL. Often, small variations of SQL need to be generated based on some parameters. SqlRender offers a simple markup syntax inside the SQL code to allow parameterization. Rendering the SQL based on parameter values is done using the renderSql() function.
+
+
+
+
++Substituting parameter values
+The @ character can be used to indicate parameter names that need to be exchange for actual parameter values when rendering. In the following example, a variable called a is mentioned in the SQL. In the call to the renderSql function the value of this parameter is defined:
sql <- "SELECT * FROM table WHERE id = @a;"
+renderSql(sql, a = 123)$sql#> [1] "SELECT * FROM table WHERE id = 123;"Note that, unlike the parameterization offered by most database management systems, it is just as easy to parameterize table or field names as values:
+sql <- "SELECT * FROM @x WHERE id = @a;"
+renderSql(sql, x = "my_table", a = 123)$sql#> [1] "SELECT * FROM my_table WHERE id = 123;"The parameter values can be numbers, strings, booleans, as well as vectors, which are converted to comma-delimited lists:
+sql <- "SELECT * FROM table WHERE id IN (@a);"
+renderSql(sql, a = c(1, 2, 3))$sql#> [1] "SELECT * FROM table WHERE id IN (1,2,3);"
+
+
+
+
++Default parameter values
+For some or all parameters, it might make sense to define default values that will be used unless the user specifies another value. This can be done using the {DEFAULT @parameter = value} syntax:
sql <- "{DEFAULT @a = 1} SELECT * FROM table WHERE id = @a;"
+renderSql(sql)$sql#> [1] "SELECT * FROM table WHERE id = 1;"renderSql(sql, a = 2)$sql#> [1] "SELECT * FROM table WHERE id = 2;"Defaults for multiple variables can be defined:
+sql <- "{DEFAULT @a = 1} {DEFAULT @x = 'my_table'} SELECT * FROM @x WHERE id = @a;"
+renderSql(sql)$sql#> [1] "SELECT * FROM my_table WHERE id = 1;"
+
+
+
+
+
+
++If-then-else
+Sometimes blocks of codes need to be turned on or off based on the values of one or more parameters. This is done using the {Condition} ? {if true} : {if false} syntax. If the condition evaluates to true or 1, the if true block is used, else the if false block is shown (if present).
sql <- "SELECT * FROM table {@x} ? {WHERE id = 1}"
+renderSql(sql, x = FALSE)$sql#> [1] "SELECT * FROM table "renderSql(sql, x = TRUE)$sql#> [1] "SELECT * FROM table WHERE id = 1"Simple comparisons are also supported:
+sql <- "SELECT * FROM table {@x == 1} ? {WHERE id = 1};"
+renderSql(sql, x = 1)$sql#> [1] "SELECT * FROM table WHERE id = 1;"renderSql(sql, x = 2)$sql#> [1] "SELECT * FROM table ;"As well as the IN operator:
sql <- "SELECT * FROM table {@x IN (1,2,3)} ? {WHERE id = 1}; "
+renderSql(sql, x = 2)$sql#> [1] "SELECT * FROM table WHERE id = 1; "
+
+
++Translation to other SQL dialects
+SQL for one platform (e.g. Microsoft SQL Server) will not always execute on other platforms (e.g. Oracle). The translateSql() function can be used to translate between different dialects, but there are some limitations.
A first limitation is that the starting dialect has to be SQL Server. The reason for this is that this dialect is in general the most specific. For example, the number of days between two dates in SQL Server has to be computed using the DATEDIFF function: DATEDIFF(dd,a,b). In other languages one can simply subtract the two dates: b-a. Since you’d need to know a and b are dates, it is not possible to go from other languages to SQL Server, only the other way around.
A second limitation is that currently only these dialects are supported as targets: Oracle, PostgreSQL, Microsoft PDW (Parallel Data Warehouse), Impala, Netezza, Google BigQuery, and Amazon Redhift.
+A third limitation is that only a limited set of translation rules have currently been implemented, although adding them to the list should not be hard.
+A last limitation is that not all functions supported in one dialect have an equivalent in other dialects.
+Below an example:
+sql <- "SELECT DATEDIFF(dd,a,b) FROM table; "
+translateSql(sql, targetDialect = "oracle")$sql#> [1] "SELECT (CAST(b AS DATE) - CAST(a AS DATE)) FROM table ; "The targetDialect parameter can have the following values:
-
+
- “oracle” +
- “postgresql” +
- “pdw” +
- “redshift” +
- “impala” +
- “netezza” +
- “bigquery” +
- “sql server” (no translation) +
+
+
+
+
++Functions and structures supported by translateSql
+These SQL Server functions have been tested and were found to be translated correctly to the various dialects:
+| Function | +Function | +Function | +Function | +
|---|---|---|---|
| ABS | +DATEDIFF | +LOG | +ROUND | +
| ACOS | +DATEFROMPARTS | +LOG10 | +ROW_NUMBER | +
| ASIN | +DATETIMEFROMPARTS | +LOWER | +RTRIM | +
| ATAN | +DAY | +LTRIM | +SIN | +
| AVG | +EOMONTH | +MAX | +SQRT | +
| CAST | +EXP | +MIN | +SQUARE | +
| CEILING | +FLOOR | +MONTH | +STDEV | +
| CHARINDEX | +GETDATE | +NEWID | +SUM | +
| CONCAT | +HASHBYTES* | +PI | +TAN | +
| COS | +ISNULL | +POWER | +UPPER | +
| COUNT | +ISNUMERIC | +RAND | +VAR | +
| COUNT_BIG | +LEFT | +RANK | +YEAR | +
| DATEADD | +LEN | +RIGHT | ++ |
-
+
- Requires special priviliges on Oracle +
Similarly, many SQL syntax structures are supported. Here is a non-exhaustive lists of things that we know will translate well:
+SELECT * FROM table; -- Simple selects
+
+SELECT * FROM table_1 INNER JOIN table_2 ON a = b; -- Selects with joins
+
+SELECT * FROM (SELECT * FROM table_1) tmp WHERE a = b; -- Nested queries
+
+SELECT TOP 10 * FROM table; -- Limiting to top rows
+
+SELECT * INTO new_table FROM table; -- Selecting into a new table
+
+CREATE TABLE table (field INT); -- Creating tables
+
+INSERT INTO other_table (field_1) VALUES (1); -- Inserting verbatim values
+
+INSERT INTO other_table (field_1) SELECT value FROM table; -- Inserting from SELECT
+
+DROP TABLE table; -- Simple drop commands
+
+IF OBJECT_ID('ACHILLES_analysis', 'U') IS NOT NULL -- Drop table if it exists
+ DROP TABLE ACHILLES_analysis;
+
+IF OBJECT_ID('tempdb..#cohorts', 'U') IS NOT NULL -- Drop temp table if it exists
+ DROP TABLE #cohorts;
+
+WITH cte AS (SELECT * FROM table) SELECT * FROM cte; -- Common table expressions
+
+SELECT ROW_NUMBER() OVER (PARTITION BY a ORDER BY b) -- OVER clauses
+ AS "Row Number" FROM table;
+
+SELECT CASE WHEN a=1 THEN a ELSE 0 END AS value FROM table; -- CASE WHEN clauses
+
+SELECT * FROM a UNION SELECT * FROM b -- UNIONs
+
+SELECT * FROM a INTERSECT SELECT * FROM b -- INTERSECTIONs
+
+SELECT * FROM a EXCEPT SELECT * FROM b -- EXCEPT
+
++String concatenation
+String concatenation is one area where SQL Server is less specific than other dialects. In SQL Server, one would write SELECT first_name + ' ' + last_name AS full_name FROM table, but this should be SELECT first_name || ' ' || last_name AS full_name FROM table in PostgreSQL and Oracle. SqlRender tries to guess when values that are being concatenated are strings. In the example above, because we have an explicit string (the space surrounded by single quotation marks), the translation will be correct. However, if the query had been SELECT first_name + last_name AS full_name FROM table, SqlRender would have had no clue the two fields were strings, and would incorrectly leave the plus sign. Another clue that a value is a string is an explicit cast to VARCHAR, so SELECT last_name + CAST(age AS VARCHAR(3)) AS full_name FROM table would also be translated correctly. To avoid ambiguity altogether, it is probable best to use the CONCAT() function to concatenate two or more strings.
+
+
+
+
++Temp tables
+Temp tables can be very useful to store intermediate results, and when used correctly can be used to dramatically improve performance of queries. In Postgres, PDW, RedShift and SQL Server temp tables have very nice properties: they’re only visible to the current user, are automatically dropped when the session ends, and can be created even when the user has no write access. Unfortunately, in Oracle temp tables are basically permanent tables, with the only difference that the data inside the table is only visible to the current user. This is why, in Oracle, SqlRender will try to emulate temp tables by
+-
+
- Adding a random string to the table name so tables from different users will not conflict. +
- Allowing the user to specify the schema where the temp tables will be created. +
For example:
+sql <- "SELECT * FROM #children;"
+translateSql(sql, targetDialect = "oracle", oracleTempSchema = "temp_schema")$sql#> [1] "SELECT * FROM temp_schema.kp8f8g5fchildren ;"Note that the user will need to have write privileges on temp_schema.
Also note that because Oracle has a limit on table names of 30 characters, temp table names are only allowed to be at most 22 characters long because else the name will become too long after appending the session ID.
+Futhermore, remember that temp tables are not automatically dropped on Oracle, so you will need to explicitly TRUNCATE and DROP all temp tables once you’re done with them to prevent orphan tables accumulating in the Oracle temp schema.
If possible, try to avoid using temp tables altogether. Sometimes one could use Common Table Expressions (CTEs) when one would normally use a temp table. For example, instead of
+SELECT * INTO #children FROM person WHERE year_of_birth > 2000;
+SELECT * FROM #children WHERE gender = 8507;you could use
+WITH children AS (SELECT * FROM person WHERE year_of_birth > 2000)
+SELECT * FROM children WHERE gender = 8507;
+
+
+
+
++Implicit casts
+One of the few points where SQL Server is less explicit than other dialects is that it allows implicit casts. For example, this code will work on SQL Server:
+CREATE TABLE #temp (txt VARCHAR);
+
+INSERT INTO #temp
+SELECT '1';
+
+SELECT * FROM #temp WHERE txt = 1;Even though txt is a VARCHAR field and we are comparing it with an integer, SQL Server will automatically cast one of the two to the correct type to allow the comparison. In contrast, other dialects such as PosgreSQL will throw an error when trying to compare a VARCHAR with an INT.
You should therefore always make casts explicit. In the above example, the last statement should be replaced with either
+SELECT * FROM #temp WHERE txt = CAST(1 AS VARCHAR);or
+SELECT * FROM #temp WHERE CAST(txt AS INT) = 1;
+
+
+
++Case sensitivity in string comparisons
+Some DBMS platforms such as SQL Server always perform string comparisons in a case-insensitive way, while others such as PostgreSQL are always case sensitive. It is therefore recommended to always assume case-sensitive comparisons, and to explicitly make comparisons case-insensitive when unsure about the case. For example, instead of
+SELECT * FROM concept WHERE concep_class_id = 'Clinical Finding'it is preferred to use
+SELECT * FROM concept WHERE LOWER(concep_class_id) = 'clinical finding'
+
+
+
+
+
++Schemas and databases
+In SQL Server, tables are located in a schema, and schemas reside in a database. For example, cdm_data.dbo.person refers to the person table in the dbo schema in the cdm_data database. In other dialects, even though a similar hierarchy often exists they are used very differently. In SQL Server, there is typically one schema per database (often called dbo), and users can easily use data in different databases. On other platforms, for example in PostgreSQL, it is not possible to use data across databases in a single session, but there are often many schemas in a database. In PostgreSQL one could say that the equivalent of SQL Server’s database is the schema.
We therefore recommend concatenating SQL Server’s database and schema into a single parameter, which we typically call @databaseSchema. For example, we could have the parameterized SQL
SELECT * FROM @databaseSchema.personwhere on SQL Server we can include both database and schema names in the value: databaseSchema = "cdm_data.dbo". On other platforms, we can use the same code, but now only specify the schema as the parameter value: databaseSchema = "cdm_data".
The one situation where this will fail is the USE command, since USE cdm_data.dbo; will throw an error. It is therefore preferred not to use the USE command, but always specify the database / schema where a table is located. However, if one wanted to use it anyway, we recommend creating two variables, one called @database and the other called @databaseSchema. For example, for this parameterized SQL:
SELECT * FROM @databaseSchema.person;
+USE @database;
+SELECT * FROM personwe can set database = "cdm_data" and the other called databaseSchema = "cdm_data.dbo". On platforms other than SQL Server, the two variables will hold the same value and only on SQL Server will they be different. Within an R function, it is even possible to derive one variable from the other, so the user of your function would need to specify only one value:
foo <- function(databaseSchema, dbms) {
+ database <- strsplit(databaseSchema, "\\.")[[1]][1]
+ sql <- "SELECT * FROM @databaseSchema.person; USE @database; SELECT * FROM person;"
+ sql <- renderSql(sql, databaseSchema = databaseSchema, database = database)$sql
+ sql <- translateSql(sql, targetDialect = dbms)$sql
+ return(sql)
+}
+foo("cdm_data.dbo", "sql server")#> [1] "SELECT * FROM cdm_data.dbo.person; USE cdm_data; SELECT * FROM person;"foo("cdm_data", "postgresql")#> [1] "SELECT * FROM cdm_data.person; SET search_path TO cdm_data; SELECT * FROM person;"
+
+
+
+
+
++Optimization for massively parallel processing
+Both PDW and RedShift are massively parallel processing platforms, meaning they consist of many nodes that work together. In such an environment, significant increases in performance can be achieved by finetuning the SQL for these platforms. Probably most importantly, developers can specify the way data is distributed over the nodes. Ideally, data in a node only needs to be combined with data in the same node. For example, if I have two tables with the field person_id, I would like all records with the same person ID to be on the same node, so a join on person_id can be performed locally without exchanging data between nodes.
SQL Server SQL, our source dialect, does not allow for these optimizations, so we’ve introduced the notion of hints. In the following example, a hint is provided on which field should be used for the distribution of data across nodes:
+--HINT DISTRIBUTE_ON_KEY(person_id)
+SELECT * INTO one_table FROM other_table;which will translate into the following on PDW:
+--HINT DISTRIBUTE_ON_KEY(person_id)
+IF XACT_STATE() = 1 COMMIT;
+CREATE TABLE one_table WITH (DISTRIBUTION = HASH(person_id)) AS
+SELECT * FROM other_table;Another tuning parameter is the key to sort a table on. This can be also be specified in a hint:
+--HINT SORT_ON_KEY(INTERLEAVED:start_date)
+CREATE TABLE cdm.my_table (row_id INT, start_date);translates to the following on RedShift:
+--HINT SORT_ON_KEY(INTERLEAVED:start_date)
+CREATE TABLE cdm.my_table (row_id INT, start_date)
+INTERLEAVED SORTKEY(start_date);The hints should be formatted exactly as shown above, and directly precede the statement where the table is created.
+
+
+
++Debugging parameterized SQL
+Debugging parameterized SQL can be a bit complicated; Only the rendered SQL can be tested against a database server, but changes to the code should be made in the parameterized (pre-rendered) SQL.
+A Shiny app is included in the SqlRender package for interactively editing source SQL and generating rendered and translated SQL. The app can be started using:
+ +Which will open the default browser with the app.
+In addition, two functions have been developed to aid the debugging process: renderSqlFile() and translateSqlFile(). These can be used to read SQL from file, render or translate it, and write it back to file. For example:
translateSqlFile("parameterizedSql.txt", "renderedSql.txt")will render the file, using the default parameter values specified in the SQL. What works well for us is editing in the parameterized file, (re)running the command above, and have the rendered SQL file open in a SQL client for testing. Any problems reported by the server can be dealt with in the source SQL, and can quickly be re-rendered.
+
+
+
+
+
++Developing R packages that contain parameterized SQL
+Often, the SQL code will become part of an R package, where it might be used to perform initial data-preprocessing and extraction before further analysis. We’ve developed the following practice for doing so: The parameterized SQL should be located in the inst/sql/ folder of the package. The parameterized SQL for SQL Server should be in the inst/sql/sql_server/ folder. If for some reason you do not want to use the translation functions to generate the SQL for some dialect (e.g because dialect specific code might be written that gives better performance), a dialect-specific version of the parameterized SQL should be placed in a folder with the name of that dialect, for example inst/sql/oracle/. SqlRender has a function loadRenderTranslateSql() that will first check if a dialect-specific version is available for the target dialect. If it is, that version will be rendered, else the SQL Server version will be rendered and subsequently translated to the target dialect.
The createRWrapperForSql() function can be used to create an R wrapper around a rendered SQL file, using the loadRenderTranslateSql() function . For example, suppose we have a text file called test.sql containing the following parameterized SQL:
{DEFAULT @selected_value = 1}
+SELECT * FROM table INTO result where x = @selected_value;Then the command
+createRWrapperForSql(sqlFilename = "test.sql",
+ rFilename = "test.R",
+ packageName = "myPackage")would result in the file test.R being generated containing this R code:
+#' Todo: add title
+#'
+#' @description
+#' Todo: add description
+#'
+#' @details
+#' Todo: add details
+#'
+#' @param connectionDetails An R object of type \code{ConnectionDetails} created ...
+#' @param selectedValue
+#'
+#' @export
+test <- function(connectionDetails, selectedValue = 1) {
+ renderedSql <- loadRenderTranslateSql("test.txt", packageName = "myPackage",
+ dbms = connectionDetails$dbms, selected_value = selectedValue)
+ conn <- connect(connectionDetails)
+
+ writeLines("Executing multiple queries. This could take a while")
+ executeSql(conn, renderedSql)
+ writeLines("Done")
+
+ dummy <- dbDisconnect(conn)
+}This code expects the file test.sql to be located in the inst/sql/sql_server/ folder of the package source.
+Note that the parameters are identified by the declaration of default values, and that snake_case names (our standard for SQL) are converted to camelCase names (our standard for R).
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/authors.html b/docs/authors.html
new file mode 100644
index 00000000..e0dd9a0c
--- /dev/null
+++ b/docs/authors.html
@@ -0,0 +1,111 @@
+
+
+
+
+
+
+
+
+
+
+
+Articles version 1.4.3
+
+
+
+
+
+
+
+
+ All vignettes
+ + +-
+
- Using SqlRender +
+
+
+
+
+
+
+
+
diff --git a/docs/jquery.sticky-kit.min.js b/docs/jquery.sticky-kit.min.js
new file mode 100644
index 00000000..e2a3c6de
--- /dev/null
+++ b/docs/jquery.sticky-kit.min.js
@@ -0,0 +1,9 @@
+/*
+ Sticky-kit v1.1.2 | WTFPL | Leaf Corcoran 2015 | http://leafo.net
+*/
+(function(){var b,f;b=this.jQuery||window.jQuery;f=b(window);b.fn.stick_in_parent=function(d){var A,w,J,n,B,K,p,q,k,E,t;null==d&&(d={});t=d.sticky_class;B=d.inner_scrolling;E=d.recalc_every;k=d.parent;q=d.offset_top;p=d.spacer;w=d.bottoming;null==q&&(q=0);null==k&&(k=void 0);null==B&&(B=!0);null==t&&(t="is_stuck");A=b(document);null==w&&(w=!0);J=function(a,d,n,C,F,u,r,G){var v,H,m,D,I,c,g,x,y,z,h,l;if(!a.data("sticky_kit")){a.data("sticky_kit",!0);I=A.height();g=a.parent();null!=k&&(g=g.closest(k));
+if(!g.length)throw"failed to find stick parent";v=m=!1;(h=null!=p?p&&a.closest(p):b(""))&&h.css("position",a.css("position"));x=function(){var c,f,e;if(!G&&(I=A.height(),c=parseInt(g.css("border-top-width"),10),f=parseInt(g.css("padding-top"),10),d=parseInt(g.css("padding-bottom"),10),n=g.offset().top+c+f,C=g.height(),m&&(v=m=!1,null==p&&(a.insertAfter(h),h.detach()),a.css({position:"",top:"",width:"",bottom:""}).removeClass(t),e=!0),F=a.offset().top-(parseInt(a.css("margin-top"),10)||0)-q,
+u=a.outerHeight(!0),r=a.css("float"),h&&h.css({width:a.outerWidth(!0),height:u,display:a.css("display"),"vertical-align":a.css("vertical-align"),"float":r}),e))return l()};x();if(u!==C)return D=void 0,c=q,z=E,l=function(){var b,l,e,k;if(!G&&(e=!1,null!=z&&(--z,0>=z&&(z=E,x(),e=!0)),e||A.height()===I||x(),e=f.scrollTop(),null!=D&&(l=e-D),D=e,m?(w&&(k=e+u+c>C+n,v&&!k&&(v=!1,a.css({position:"fixed",bottom:"",top:c}).trigger("sticky_kit:unbottom"))),e
+
+
+
+
+
+
+
+
+
+
+
++Introduction
+This is an R package for rendering parameterized SQL, and translating it to different SQL dialects. SqlRender can also be used as a stand-alone Java library and a command-line executable.
+
+
++Features
+-
+
- Supports a simple markup syntax for making SQL parameterized, and renders parameterized SQL (containing the markup syntax) to executable SQL +
- The syntax supports defining default parameter values +
- The syntax supports if-then-else structures +
- Has functions for translating SQL from one dialect (Microsoft SQL Server) to other dialects (Oracle, PostgreSQL, Amazon RedShift, Impala, IBM Netezza, Google BigQuery, and Microsoft PDW) +
- Can be used as R package, Java library, or as stand-alone executable through a command-line interface +
+
+
+
++Examples
+This exampe shows the use of parameters, as well as SqlRender’s {if} ? {then} : {else} syntax:
+sql <- renderSql("SELECT * FROM @a; {@b != ''}?{USE @b;}", a = "my_table", b = "my_schema")$sqlwill produce the variable sql containing this value:
"SELECT * FROM my_table; USE my_schema;"subsequently running this code
+sql <- translateSql(sql, "sql server", "oracle")$sqlwill produce the variable sql containing this value:
"SELECT * FROM my_table; ALTER SESSION SET current_schema = my_schema;"
+
++Technology
+The SqlRender package is an R package wrapped around a Java library. The rJava package is used as interface.
+The Java library is available as a JAR file.
+
+
+
++System Requirements
+Running the package requires R with the package rJava installed. Also requires Java 1.6 or higher.
+
+
++Getting Started
+
+
+
+
+
++R package
+In R, use the following commands to install the latest stable version from CRAN:
+install.packages("SqlRender")To install the latest development version directly from GitHub, use:
+install.packages("devtools")
+library(devtools)
+install_github("ohdsi/SqlRender")Once installed, you can try out SqlRender in a Shiny app that comes with the package:
+library(SqlRender)
+launchSqlRenderDeveloper()
+
+
++Java library
+You can fetch the JAR file in the inst/java folder of this repository, or use Maven:
+-
+
-
+
First add the SqlRender repository so that maven can find and download the SqlRender artifact automatically:
++<repositories> +<repository> + <id>ohdsi</id> + <name>repo.ohdsi.org</name> + <url>http://repo.ohdsi.org:8085/nexus/content/repositories/releases</url> +</repository> +<repository> + <id>ohdsi.snapshots</id> + <name>repo.ohdsi.org-snapshots</name> + <url>http://repo.ohdsi.org:8085/nexus/content/repositories/snapshots</url> + <releases> + <enabled>false</enabled> + </releases> + <snapshots> + <enabled>true</enabled> + </snapshots> +</repository> +</repositories>2: Include the SqlRender dependency in your pom.xml
++<dependency> +<groupId>org.ohdsi.sql</groupId> +<artifactId>SqlRender</artifactId> +<version>1.0.0-SNAPSHOT</version> +</dependency>
+
+
+
+
+
+
+ +Getting Involved
+-
+
- Vignette: Using SqlRender + +
- Package manual: SqlRender manual + +
- Developer questions/comments/feedback: OHDSI Forum + +
- We use the GitHub issue tracker for all bugs/issues/enhancements +
+
+Links
+-
+
- Download from CRAN at
https://cran.r-project.org/package=SqlRender +
+ - Browse source code at
https://github.com/OHDSI/SqlRender +
+ - Report a bug at
https://github.com/OHDSI/SqlRender/issues +
+
License
+Apache License 2.0
+Developers
+-
+
- Martijn Schuemie
Author, maintainer
+ - Marc Suchard
Author
+
Dev status
+-
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/camelCaseToSnakeCase.html b/docs/reference/camelCaseToSnakeCase.html
new file mode 100644
index 00000000..72bff165
--- /dev/null
+++ b/docs/reference/camelCaseToSnakeCase.html
@@ -0,0 +1,131 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ SqlRender
+SqlRender
+ + + + +
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/createRWrapperForSql.html b/docs/reference/createRWrapperForSql.html
new file mode 100644
index 00000000..7ede8d0f
--- /dev/null
+++ b/docs/reference/createRWrapperForSql.html
@@ -0,0 +1,153 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Convert a camel case string to snake case
+Convert a camel case string to snake case
+ + +camelCaseToSnakeCase(string)+ +
Arguments
+| string | +The string to be converted |
+
|---|
Value
+ +A string
+ + +Examples
++camelCaseToSnakeCase("cdmDatabaseSchema")#> [1] "cdm_database_schema"# > 'cdm_database_schema'
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/index.html b/docs/reference/index.html
new file mode 100644
index 00000000..1f68ea1d
--- /dev/null
+++ b/docs/reference/index.html
@@ -0,0 +1,205 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Create an R wrapper for SQL
+createRWrapperForSql creates an R wrapper for a parameterized SQL file. The created R script
+file will contain a single function, that executes the SQL, and accepts the same parameters as
+specified in the SQL.
createRWrapperForSql(sqlFilename, rFilename, packageName, + createRoxygenTemplate = TRUE)+ +
Arguments
+| sqlFilename | +The SQL file. |
+
|---|---|
| rFilename | +The name of the R file to be generated. Defaults to the name of the +SQL file with the extention reset to R. |
+
| packageName | +The name of the package that will contains the SQL file. |
+
| createRoxygenTemplate | +If true, a template of Roxygen comments will be added. |
+
Details
+ +This function reads the declarations of defaults in the parameterized SQL file, and creates an R
+function that exposes the parameters. It uses the loadRenderTranslateSql function, and
+assumes the SQL will be used inside a package. To use inside a package, the SQL file should be
+placed in the inst/sql/sql_server folder of the package.
Examples
++not_run({ + # This will create a file called CohortMethod.R: + createRWrapperForSql("CohortMethod.sql", packageName = "CohortMethod") +})
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/launchSqlRenderDeveloper.html b/docs/reference/launchSqlRenderDeveloper.html
new file mode 100644
index 00000000..129592fd
--- /dev/null
+++ b/docs/reference/launchSqlRenderDeveloper.html
@@ -0,0 +1,128 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Reference + version 1.4.3 +
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/loadRenderTranslateSql.html b/docs/reference/loadRenderTranslateSql.html
new file mode 100644
index 00000000..e4616795
--- /dev/null
+++ b/docs/reference/loadRenderTranslateSql.html
@@ -0,0 +1,165 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Launch the SqlRender Developer Shiny app
+Launch the SqlRender Developer Shiny app
+ + +launchSqlRenderDeveloper(launch.browser = TRUE)+ +
Arguments
+| launch.browser | +Should the app be launched in your default browser, or in a Shiny window. +Note: copying to clipboard will not work in a Shiny window. |
+
|---|
Details
+ +Launches a Shiny app that allows the user to develop SQL and see how it translates to the supported dialects.
+ + +
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/readSql.html b/docs/reference/readSql.html
new file mode 100644
index 00000000..feffb48f
--- /dev/null
+++ b/docs/reference/readSql.html
@@ -0,0 +1,139 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Load, render, and translate a SQL file in a package
+loadRenderTranslateSql Loads a SQL file contained in a package, renders it and translates it
+to the specified dialect
loadRenderTranslateSql(sqlFilename, packageName, dbms = "sql server", ..., + oracleTempSchema = NULL)+ +
Arguments
+| sqlFilename | +The source SQL file |
+
|---|---|
| packageName | +The name of the package that contains the SQL file |
+
| dbms | +The target dialect. Currently 'sql server', 'oracle', 'postgres', and +'redshift' are supported |
+
| ... | +Parameter values used for |
+
| oracleTempSchema | +A schema that can be used to create temp tables in when using Oracle. |
+
Value
+ +Returns a string containing the rendered SQL.
+ +Details
+ +This function looks for a SQL file with the specified name in the inst/sql/<dbms> folder of the
+specified package. If it doesn't find it in that folder, it will try and load the file from the
+inst/sql/sql_server folder and use the translateSql function to translate it to the
+requested dialect. It will subsequently call the renderSql function with any of the
+additional specified parameters.
Examples
++not_run({ + renderedSql <- loadRenderTranslateSql("CohortMethod.sql", + packageName = "CohortMethod", + dbms = connectionDetails$dbms, + CDM_schema = "cdmSchema") +})
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/renderSql.html b/docs/reference/renderSql.html
new file mode 100644
index 00000000..c74f876e
--- /dev/null
+++ b/docs/reference/renderSql.html
@@ -0,0 +1,244 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Reads a SQL file
+readSql loads SQL from a file
readSql(sourceFile)+ +
Arguments
+| sourceFile | +The source SQL file |
+
|---|
Value
+ +Returns a string containing the SQL.
+ +Details
+ +readSql loads SQL from a file
Examples
++not_run({ + readSql("myParamStatement.sql") +})
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/renderSqlFile.html b/docs/reference/renderSqlFile.html
new file mode 100644
index 00000000..facdd4e5
--- /dev/null
+++ b/docs/reference/renderSqlFile.html
@@ -0,0 +1,148 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ renderSql
+renderSql Renders SQL code based on parameterized SQL and parameter values.
renderSql(sql = "", ...)+ +
Arguments
+| sql | +The parameterized SQL |
+
|---|---|
| ... | +Parameter values |
+
Value
+ +A list containing the following elements:
-
+
- parameterizedSql
The original +parameterized SQL code
- sql
The rendered sql
Details
+ +This function takes parameterized SQL and a list of parameter values and renders the SQL that can +be send to the server. Parameterization syntax:
-
+
- @parameterName
Parameters are +indicated using a @ prefix, and are replaced with the actual values provided in the renderSql +call.
- {DEFAULT @parameterName = parameterValue}
Default values for parameters can be +defined using curly and the DEFAULT keyword.
- {if}?{then}:{else}
The if-then-else +pattern is used to turn on or off blocks of SQL code.
Examples
++renderSql("SELECT * FROM @a;", a = "myTable")#> $originalSql +#> [1] "SELECT * FROM @a;" +#> +#> $sql +#> [1] "SELECT * FROM myTable;" +#> +#> $parameters +#> $parameters$a +#> [1] "myTable" +#> +#>renderSql("SELECT * FROM @a {@b}?{WHERE x = 1};", a = "myTable", b = "true")#> $originalSql +#> [1] "SELECT * FROM @a {@b}?{WHERE x = 1};" +#> +#> $sql +#> [1] "SELECT * FROM myTable WHERE x = 1;" +#> +#> $parameters +#> $parameters$a +#> [1] "myTable" +#> +#> $parameters$b +#> [1] "true" +#> +#>renderSql("SELECT * FROM @a {@b == ''}?{WHERE x = 1}:{ORDER BY x};", a = "myTable", b = "true")#> $originalSql +#> [1] "SELECT * FROM @a {@b == ''}?{WHERE x = 1}:{ORDER BY x};" +#> +#> $sql +#> [1] "SELECT * FROM myTable ORDER BY x;" +#> +#> $parameters +#> $parameters$a +#> [1] "myTable" +#> +#> $parameters$b +#> [1] "true" +#> +#>renderSql("SELECT * FROM @a {@b != ''}?{WHERE @b = 1};", a = "myTable", b = "y")#> $originalSql +#> [1] "SELECT * FROM @a {@b != ''}?{WHERE @b = 1};" +#> +#> $sql +#> [1] "SELECT * FROM myTable WHERE y = 1;" +#> +#> $parameters +#> $parameters$a +#> [1] "myTable" +#> +#> $parameters$b +#> [1] "y" +#> +#>renderSql("SELECT * FROM @a {1 IN (@c)}?{WHERE @b = 1};", + a = "myTable", + b = "y", + c = c(1, 2, 3, 4))#> $originalSql +#> [1] "SELECT * FROM @a {1 IN (@c)}?{WHERE @b = 1};" +#> +#> $sql +#> [1] "SELECT * FROM myTable WHERE y = 1;" +#> +#> $parameters +#> $parameters$a +#> [1] "myTable" +#> +#> $parameters$b +#> [1] "y" +#> +#> $parameters$c +#> [1] "1,2,3,4" +#> +#>renderSql("{DEFAULT @b = \"someField\"}SELECT * FROM @a {@b != ''}?{WHERE @b = 1};", + a = "myTable")#> $originalSql +#> [1] "{DEFAULT @b = \"someField\"}SELECT * FROM @a {@b != ''}?{WHERE @b = 1};" +#> +#> $sql +#> [1] "SELECT * FROM myTable WHERE someField = 1;" +#> +#> $parameters +#> $parameters$a +#> [1] "myTable" +#> +#>renderSql("SELECT * FROM @a {@a == 'myTable' & @b != 'x'}?{WHERE @b = 1};", + a = "myTable", + b = "y")#> $originalSql +#> [1] "SELECT * FROM @a {@a == 'myTable' & @b != 'x'}?{WHERE @b = 1};" +#> +#> $sql +#> [1] "SELECT * FROM myTable WHERE y = 1;" +#> +#> $parameters +#> $parameters$a +#> [1] "myTable" +#> +#> $parameters$b +#> [1] "y" +#> +#>
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/snakeCaseToCamelCase.html b/docs/reference/snakeCaseToCamelCase.html
new file mode 100644
index 00000000..ab794ad1
--- /dev/null
+++ b/docs/reference/snakeCaseToCamelCase.html
@@ -0,0 +1,131 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Render a SQL file
+renderSqlFile Renders SQL code in a file based on parameterized SQL and parameter values,
+and writes it to another file.
renderSqlFile(sourceFile, targetFile, ...)+ +
Arguments
+| sourceFile | +The source SQL file |
+
|---|---|
| targetFile | +The target SQL file |
+
| ... | +Parameter values |
+
Details
+ +This function takes parameterized SQL and a list of parameter values and renders the SQL that can +be send to the server. Parameterization syntax:
-
+
- @parameterName
Parameters are +indicated using a @ prefix, and are replaced with the actual values provided in the renderSql +call.
- {DEFAULT @parameterName = parameterValue}
Default values for parameters can be +defined using curly and the DEFAULT keyword.
- {if}?{then}:{else}
The if-then-else +pattern is used to turn on or off blocks of SQL code.
Examples
++not_run({ + renderSqlFile("myParamStatement.sql", "myRenderedStatement.sql", a = "myTable") +})
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/splitSql.html b/docs/reference/splitSql.html
new file mode 100644
index 00000000..734442a4
--- /dev/null
+++ b/docs/reference/splitSql.html
@@ -0,0 +1,139 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Convert a snake case string to camel case
+Convert a snake case string to camel case
+ + +snakeCaseToCamelCase(string)+ +
Arguments
+| string | +The string to be converted |
+
|---|
Value
+ +A string
+ + +Examples
++snakeCaseToCamelCase("cdm_database_schema")#> [1] "cdmDatabaseSchema"# > 'cdmDatabaseSchema'
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/translateSql.html b/docs/reference/translateSql.html
new file mode 100644
index 00000000..61e4f346
--- /dev/null
+++ b/docs/reference/translateSql.html
@@ -0,0 +1,162 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ splitSql
+splitSql splits a string containing multiple SQL statements into a vector of SQL statements
splitSql(sql)+ +
Arguments
+| sql | +The SQL string to split into separate statements |
+
|---|
Value
+ +A vector of strings, one for each SQL statement
+ +Details
+ +This function is needed because some DBMSs (like ORACLE) do not accepts multiple SQL statements +being sent as one execution.
+ + +Examples
++splitSql("SELECT * INTO a FROM b; USE x; DROP TABLE c;")#> [1] "SELECT * INTO a FROM b" "USE x" "DROP TABLE c"+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/translateSqlFile.html b/docs/reference/translateSqlFile.html
new file mode 100644
index 00000000..d2f92f69
--- /dev/null
+++ b/docs/reference/translateSqlFile.html
@@ -0,0 +1,154 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ translateSql
+translateSql translates SQL from one dialect to another
translateSql(sql = "", targetDialect, oracleTempSchema = NULL, + sourceDialect)+ +
Arguments
+| sql | +The SQL to be translated |
+
|---|---|
| targetDialect | +The target dialect. Currently "oracle", "postgresql", "pdw", "impala", "netezza", "bigquery", and +"redshift" are supported |
+
| oracleTempSchema | +A schema that can be used to create temp tables in when using Oracle or Impala. |
+
| sourceDialect | +Deprecated: The source dialect. Currently, only "sql server" for Microsoft SQL Server +is supported |
+
Value
+ +A list containing the following elements:
-
+
- originalSql
The original parameterized +SQL code
- sql
The translated SQL
Details
+ +This function takes SQL in one dialect and translates it into another. It uses simple pattern +replacement, so its functionality is limited.
+ + +Examples
++translateSql("USE my_schema;", targetDialect = "oracle")#> $originalSql +#> [1] "USE my_schema;" +#> +#> $sql +#> [1] "ALTER SESSION SET current_schema = my_schema;" +#>+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/writeSql.html b/docs/reference/writeSql.html
new file mode 100644
index 00000000..c2270ebc
--- /dev/null
+++ b/docs/reference/writeSql.html
@@ -0,0 +1,138 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Translate a SQL file
+This function takes SQL and translates it to a different dialect.
+ + +translateSqlFile(sourceFile, targetFile, sourceDialect, targetDialect, + oracleTempSchema = NULL)+ +
Arguments
+| sourceFile | +The source SQL file |
+
|---|---|
| targetFile | +The target SQL file |
+
| sourceDialect | +Deprecated: The source dialect. Currently, only 'sql server' for Microsoft SQL Server +is supported |
+
| targetDialect | +The target dialect. Currently 'oracle', 'postgresql', and 'redshift' are +supported |
+
| oracleTempSchema | +A schema that can be used to create temp tables in when using Oracle. |
+
Details
+ +This function takes SQL and translates it to a different dialect.
+ + +Examples
++not_run({ + translateSqlFile("myRenderedStatement.sql", + "myTranslatedStatement.sql", + targetDialect = "postgresql") +})
+
+
+
+
+
+
+
+
+
+
diff --git a/extras/PackageMaintenance.R b/extras/PackageMaintenance.R
index bb07bb3e..892879ca 100644
--- a/extras/PackageMaintenance.R
+++ b/extras/PackageMaintenance.R
@@ -1,6 +1,6 @@
# @file PackageMaintenance
#
-# Copyright 2016 Observational Health Data Sciences and Informatics
+# Copyright 2017 Observational Health Data Sciences and Informatics
#
# This file is part of SqlRender
#
@@ -29,4 +29,11 @@ rmarkdown::render("vignettes/UsingSqlRender.Rmd",
output_file = "../inst/doc/UsingSqlRender.pdf",
rmarkdown::pdf_document(latex_engine = "pdflatex",
toc = TRUE,
- number_sections = TRUE))
\ No newline at end of file
+ number_sections = TRUE))
+
+pkgdown::build_site()
+
+# Release package:
+devtools::build_win()
+
+devtools::release()
diff --git a/extras/SqlRender.pdf b/extras/SqlRender.pdf
index 897badcd..6140501f 100644
Binary files a/extras/SqlRender.pdf and b/extras/SqlRender.pdf differ
diff --git a/inst/csv/replacementPatterns.csv b/inst/csv/replacementPatterns.csv
index 1b0ab6ec..5f20e2c8 100644
--- a/inst/csv/replacementPatterns.csv
+++ b/inst/csv/replacementPatterns.csv
@@ -1,385 +1,489 @@
-From,To,Pattern,Replacement
-"sql server","oracle","INSERT INTO @table (@columns) VALUES (@values1),(@values2)","
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Write SQL to a SQL (text) file
+writeSql writes SQL to a file
writeSql(sql, targetFile)+ +
Arguments
+| sql | +A string containing the sql |
+
|---|---|
| targetFile | +The target SQL file |
+
Details
+ +writeSql writes SQL to a file
Examples
++not_run({ + sql <- "SELECT * FROM @table_name" + writeSql(sql, "myParamStatement.sql") +})