Using the Database Client with Snowflake
Snowflake is a cloud-based database which can be used as an RDBMS for the NLP API database. Compatibility with the NLP API database client is achieved using the Snowflake plugin for SQLAlchemy, the ORM that the NLP API database client uses. This document aims to walk the user through installing the Snowflake plugin for SQLAlchemy, as well as creating a Snowflake-based NLP API database and schema and processing documents with the emtellPro client for storage in a Snowflake-based NLP API database.
Prerequisites
Set up the environment variables used in this guide for access to the NLP API server. You will need to set the following environment variables for the NLP API server and your access and secret keys. If you do not have access to the appropriate values for these variables please contact us.
Direct Insertion into Snowflake
The steps for this howto are:
- Install the NLP API Database Client and Snowflake SQLAlchemy plugin
- Create a database in Snowflake
- Create the NLP API tables/schema in the new database
- Process a document and store the output in the new database
Step 1: Install the Required Software
These instructions are for Linux; however performing these steps on MacOS or Windows will be similar but may require slight changes to the commands depending on the OS and shell used.
First, download and install the SDK/clients using the instructions from Database client usage. Or, for convenience, the commands to run to install the basic and database clients are:
Now, let’s install the Snowflake plugin for SQLAlchemy:
If you already had snowflake-sqlalchemy installed, ensure that it’s at least version 1.6.1. Earlier versions will lead to an exception being raised.
Finally, you should test your installation to ensure that the NLP API database client is working. Ensure that you’re still within the Python virtualenv and execute the following:
If you have a working NLP API database client, you should see output similar to:
Step 2: Create a Database in Snowflake
The screenshots and commands in this section may vary slightly for your version of Snowflake.
First, go to the ‘Warehouses’ tab in the Snowflake UI and ensure that the warehouse that you’re going to use is in status Started, as shown in the screenshot below:

Note that the name of our warehouse in this case is COMPUTE_WH as we will use this name again shortly. If the warehouse that you want to use is not in Started status, then you’ll need to start it before proceeding.
Next, click on the ‘Databases’ tab in the Snowflake UI and click on the ‘Create’ button to create a new database. In this case, we’ve called our new database EMTELLIPRO, as shown in the screenshot below:

For the purposes of this howto, we’re just going to use the sysadmin’s username to access this database; we don’t need to set any additional privileges or do anything else at this point.
Step 3: Create the NLP API Tables
Next, we’ll use emtellipro-db-client to create the tables for storing the NLP API output in our new database. For this step, make sure that you’re inside the Python virtual environment that we created in Step 1 above. If you have dropped out of the Python venv, you can get back inside of it with:
You should take a minute to gather your variables, as there are quite a few in this step. The variables we’re going to need are:
<snowflake_username>- the Snowflake username we’ll use for this database<snowflake_password>- the Snowflake password for the account that we are using<snowflake_account>- the Snowflake account that we are using<snowflake_database>- the name of the database we created above (in this case, it isEMTELLIPRO)<snowflake_schema>- the Snowflake schema name that we are using (we will use the default schema ofPUBLIC)<snowflake_warehouse>- the name for our Snowflake warehouse (in this case, it isCOMPUTE_WH)<snowflake_role>- the Snowflake role name that we are using (for this username, it isSYSADMIN)
Now, let’s build the Snowflake URL that we are going to use for accessing our Snowflake database, which we’ll use in this step and in Step 4 below. It has the following format:
The URL format is documented in Snowflake’s SQLAlchemy driver documentation.
This differs from the URL format Snowflake describes on its other pages, but as the URL is passed along unchanged to Snowflake’s driver, only the format described at the above link will work.
Once we have plugged our variables into the URL, we can use it with the NLP API database client’s create-db command as follows:
Note that the use of double-quotes in the example above are necessary to get bash to parse the command properly, and that the line continuation character of \ is bash-specific; different shells (like the Windows command interpreter) use different characters for this. If this command is successful in creating the tables, the database client should echo something back like:
And in the Snowflake UI, the tables that were just created will be visible in the EMTELLIPRO database as shown below (note that more tables are present than those shown in the screenshot):

Using private keys for authentication
All commands in the Python database client also take --snowflake-private-key-path as an option alongside --database. This option should be set to the path of the private key used for connecting to Snowflake. If using this option, omit the password <snowflake_password> in the connection URL above. To be consistent with SnowSQL, the passphrase for this key file can be passed using $SNOWFLAKE_PRIVATE_KEY_PASSPHRASE or $SNOWSQL_PRIVATE_KEY_PASSPHRASE in the environment, or if those environment variables are not set, the client will prompt for the passphrase if necessary. Both encrypted and unencrypted key files are supported.
Step 4: Process a Sample Report and Store the Output in the Snowflake Database
In this processing example, we will use the Snowflake URL that we built in Step 3 above, and we will process the sample CT scan report that is in the Python SDK in the file example-data/sample_ct_report.txt.
Again, inside of the Python virtual environment that has been used in these steps, we will process the sample CT scan report with the command below. Note that the variables $EMTELLIPRO_ACCESS_KEY, $EMTELLIPRO_SHARED_SECRET, and $EMTELLIPRO_SERVER are for the public access key, secret key, and the NLP API server API URL that you are using. These should be assigned to you by Emtelligent or your system administrator.
If this command is successful, we should see output similar to the following:
The output above shows a successful processing and saving of a document to the Snowflake NLP API database that we have created. Note that the storage performance when using a hosted, cloud-based Snowflake instance can be less than that of a locally-hosted database due to network packetization and transit delays.
We can now go back to the Snowflake UI, and in the ‘Worksheets’ tab, select the EMTELLIPRO database and execute a simple query such as:
From processing the sample_ct_report.txt document above, we would then expect to see output (based on the current version of the NLP API) similar to the following:

If you can see data similar to the above with this query, then you have been able to successfully process and store data from the NLP API into a Snowflake-based NLP API database. For further reading on SQL queries, please see the documentation on the NLP API database schema.
Access JSON data in Snowflake
Depending on the options provided to the Python database client, the entire JSON output from the NLP API can be stored in the document table in the NLP API database. The JSON is stored in the JSON_REPRESENTATION column in the document table as a varchar type. In order to access the JSON data in Snowflake the parse_json SQL command is necessary.
This SQL statement returns a single column table of the task ids stored in the JSON.
CSV uploads to Snowflake
This process is much faster than the direct insertion into a Snowflake database described above. Using CSV uploads the concepts table might contain duplicates as Snowflake does not enforce the uniqueness constraint for file uploads. The user will have to run a post-process step to remove the duplicates or at least be aware of these duplicates in the concept table when writing the SQL queries against the database.
Steps 1 through 3 are the same as in the above section about direct insertion into a Snowflake database. Step 4 onwards will be different: we will create CSV files as the output NLP API database and then upload the CSV files to a Snowflake database.
Step 4: Process Data and Store the Output in CSV Files
This section provides an example processing run of some input data and storing the output in CSV files that can be then uploaded to the Snowflake database created in Steps 1 through 3 from the previous section.
Step 4a
First create a directory to store the CSV files. For this example, let’s call this the csv_output directory.
Step 4b
Use the emtellipro database client to initialize the CSV output files using create-db. I’m using the csv_output directory.
Step 4c
Process some Clinical text documents stored in the files reports*.txt and store the output as CSV files to the directory csv_output.
Step 5: Use snowsql to upload the CSV files
Set up snowsql with the appropriate command line parameters or create a config file by following the Snowflake documentation for snowsql.
Make sure you are in the directory where the csv files were created (csv_output in our running example) or modify the script with the path to the csv files. You may want to timestamp the csv files but the script provided below simply removes the staged files after the insertion into the snowflake database is done. The sample script below does not do a lot of error checking and it just removes the uploaded csv files so please examine the script carefully and try it on sample data before running it on production data.
Assume that using Steps 1 through 3 of the previous section, the database EMTELLIPRO has been created on Snowflake and the NLP API tables have been created using the create-db option in the Python database client. Also we assume below you have a config file setup for snowsql for the EMTELLIPRO database on Snowflake.
Save the snowsql code provided at the end of this section to the file snowflake_upload.sql and then run the SQL code using snowsql.
In the snowsql interpreter type in:
The NLP API database will be available on Snowflake once the upload completes successfully.
The Snowflake database can be queried just like the database created through direct insertion into Snowflake from the previous section.
The SQL code for snowflake_upload.sql (download link):

