Skip to content

Connecting

Info

This guide assumes that you have a Nexus account with Expert privileges. If this is not the case, request an account upgrade first from .

Connecting to Nexus Database

Nexus uses a PostgreSQL relational database to maintain an always up-to-date copy of connected data sources. You can connect to Nexus Database using any JDBC/ODBC client.

The easiest way to visually inspect available data is to use the PostgreSQL client tool; DBeaver. This tool can be downloaded here (free and open source). After installation, start DBeaver, and add Nexus Database as a new server using the login credentials provided in the Expert confirmation email.

In addition to DBeaver, you can also work with geospatial tables in Nexus Database using common desktop GIS applications, like for example QGIS or ArcGIS (version 10.1 and higher). Finally, Nexus can also be connected to BI software. For Tableau, follow our tutorial.

Note

Each Expert account can have up to 3 simultaneous database connections, enabling parallel data access (useful for working with multiple applications at the same time). Ensure that unused connections are properly closed before opening additional ones to avoid exceeding this limit.

First look at the database

Navigate to the geodata_cache database. The main structure of the database consists of schemas and tables. Each world in Nexus corresponds to a database schema. Thus, within a schema you'll find all data of a particular organization using Nexus. Your Expert confirmation email lists all worlds to which you have read access.

The 'sandbox' is a universal playground world, covering roughly the province of Utrecht in the Netherlands, intended for demo applications and testing calculations. All accounts with Expert privileges have read access rights to this world, hence you can check it out in DBeaver.

Data in each world is of one of the following four categories:

  • Vector features
  • Timeseries
  • Rasters
  • Files

Each vector feature type is stored in its own database table. Timeseries, raster and file metadata is stored in equally named tables, with timeseries events in the event table and actual rasters and files on a separate Datastore. Check the Nexus data model background to learn about how data is organized in Nexus and the guide on Expert API reading data for more details about the raw data interface for developers.

Developing your calculation

Nexus supports calculations in any programming language (Python, R, Fortran, C, you name it, we got it covered!). You can even package entire existing scientific simulation models into your calculation. While developing, you can simply run your calculation from your favorite code editor or command line. Your should pull its input data directly from Nexus Database and/or Nexus Datastore.

Let's try it out - using Nexus data in Python

Assuming you're using Python, open your favorite code editor and write the following code:

import pandas as pd
import sqlalchemy

# Enter here the credentials provided in the Expert confirmation email
user = YOUR_DATABASE_USERNAME
password = YOUR_NEXUS_PASSWORD
host = DB_HOSTNAME
name = DB_NAME

engine = sqlalchemy.create_engine(f"postgresql://{user}:{password}@{host}:5432/{name}", client_encoding='utf8')

# Select all buildings constructed between 2015 and 2020
df_buildings = pd.read_sql(f"select * from sandbox.building \
                           where construction_year >= 2015 and construction_year < 2020", engine)

# Use the data in your calculation/visualization
df_buildings.hist(bins=5)

out, bins  = pd.cut(df_buildings, bins=5, include_lowest=True, right=False, retbins=True)

Deploying your calculation

You can run calculations on your local computer, but the cool thing is that Nexus is able to run your calculation operationally in the cloud. This allows your calculation results to be visualized in the web viewer and retrieved through the Nexus Web API. More importantly even, Nexus will automatically run your calculation whenever the input data changes (or trigger it on fixed intervals), so that the output is always up-to-date with the latest data.

To achieve this, keep the following things in mind:

  • Your calculation should be registered in Nexus. To register it, email mentioning the name of your calculation
  • Nexus can only visualize your calculation results if the output is stored in Nexus Database/Datastore as raw data. Any intermediate output, such as visualizations, that are produced as part of the calculation, will be discarded.
  • Your calculation should be packaged in a Docker container and then uploaded to Nexus

Check the Deployment guide section for more details.