Navigating Data

SlashDB uses a Resource Oriented Architecture. This means that data from a resource - a table in a database - can be retrieved by sending an HTTP request to a URL that is unique for each resource. The URL contains information about what database to use, what table to retrieve from, what columns to retrieve, and what columns to filter by.

Info

See Concepts for more details about how Data Discovery works.

See the Databases Configuration documentation to learn about creating database connections, configuring them, and changing a database's connection state.

There are two ways to navigate the databases that are configured in SlashDB - using a browser or by directly accessing a URL.

Important

Users must be given access to databases before they can navigate them. See the User Configuration documentation for more info.

List of Databases

The Data Discovery top-level page provides a list of all the databases that may be accessed by the browser or via REST API. It can be accessed at the /db endpoint.

The list can be searched using the Search field above the list or sorted by clicking on column headers. The Select Database Type dropdown filters the list by database type.

The list contains the following columns:

the Database ID is the name of the database as defined when creating a new database connection. Clicking on it will open a page with a view of all the database tables.

Important

Every database connected to SlashDB can be accessed by using the /db/[database_id] URL. Additionally, all tables in the database are accessed by using this URL in the form /db/[database_id]/[table_name]

the vendor Type of the database
a Description of the database
the connection Status of the database

The list can also be viewed in JSON, XML, or CSV format by clicking the button in the top right corner.

Actions

Click on the List icon to view a pane with more details about the Status

The SlashDB web interface provides a user-friendly way of navigating data using a web browser. You may see some common elements on these screens:

Any resource with these buttons in the top right corner can be viewed in JSON, XML, or CSV format by clicking on the button.

You may also see the the DATA/SCHEMA dropdown in the top right corner of some screens. Use it to switch between viewing the resource data and the resource schema.

List of Tables

From the database list, click on a database ID to open a view of all the tables in the database.

Table Records

From the tables list, click on a table name to open a view of all the records in the table.

With table records, you can:

view just one column of records by clicking on the column header name
sort records by clicking on the Sort icon in each column header
filter records by clicking on a non-primary key value for a record.
follow table relationships by clicking the Link icons
- a Link in a column header (e.g. ) will take you to the related table
- a Link in a row will take you to the table record for the foreign key value in that row

If the table contains a large number of records, they won't all be displayed at once. You can use the Next and Previous buttons to scroll through pages of records.

Single Record

From the table records view, click on a record's primary key to open a view of the record.

Info

Single resources can be updated or deleted in the browser.

Clicking on any value in the record will display the single value.

You can navigate databases and their resources by using URLs. URLs are always available in HTML, JSON, XML, and CSV format. When no extension is provided, HTML format is assumed. Segments are added to the URL as you request a more granular resource - starting from a list of databases, all the way to a single value from a record.

Important

These URLs expose the SlashDB REST API. It is a very powerful way of accessing resources.

With the REST API, you can:

access all Resource Types
perform complex Filtering against any resource
create, read, update, or delete multiple records at a time
use modifiers to control or transform output

The Data Discovery GUI itself is a working demonstration of what you can achieve by using the API to retrieve resources, update records, and follow relationships, since it is based on these URLs itself.

The examples below showcase only a portion of what you can do with a URL. Review the links above for more details.

List of Databases

To access the list of databases, use the /db URL.

Example

/db.json - get the database list in JSON format:

[
  {
      "db_id": "Chinook",
      "__href": "/db/Chinook.json",
      "type": "sqlite",
      "description": "Chinook -  SQLite @ SlashDB Beta Server",
      "status": "Connected"
  }
]

List of Tables

To access a list of tables in a database, use the /db/[database_id] URL.

Example

/db/Chinook.json - get the table list for the Chinook database in JSON format:

{
    "Chinook": {
        "__href": "/db/Chinook.json",
        "Album": "/db/Chinook/Album.json",
        "Artist": "/db/Chinook/Artist.json",
        "Customer": "/db/Chinook/Customer.json",
        "Employee": "/db/Chinook/Employee.json",
        "Genre": "/db/Chinook/Genre.json",
        "Invoice": "/db/Chinook/Invoice.json",
        "InvoiceLine": "/db/Chinook/InvoiceLine.json",
        "MediaType": "/db/Chinook/MediaType.json",
        "Playlist": "/db/Chinook/Playlist.json",
        "PlaylistTrack": "/db/Chinook/PlaylistTrack.json",
        "Track": "/db/Chinook/Track.json"
    }
}

Table Records

To access the records in a table, use the /db/[database_id]/[table_name] URL.

See Resource Types - List of Objects for more info.

Important

Use the limit modifier to limit the number of records SlashDB returns from a table.

You can also apply Filtering at the table or record level to return only records that contain specific values.

Read about Resource Types to learn how to retrieve only select columns from a table or record.

Example

/db/Chinook/Customer.json?limit=2 - get the Chinook Customer table records in JSON format:

[
    {
        "__href": "/db/Chinook/Customer/CustomerId/1.json",
        "Employee": {
            "__href": "/db/Chinook/Customer/CustomerId/1/Employee.json"
        },
        "CustomerId": 1,
        "FirstName": "Lu\u00eds",
        "LastName": "Gon\u00e7alves",
        "Company": "Embraer - Empresa Brasileira de Aeron\u00e1utica S.A.",
        "Address": "Av. Brigadeiro Faria Lima, 2170",
        "City": "S\u00e3o Jos\u00e9 dos Campos",
        "State": "SP",
        "Country": "Brazil",
        "PostalCode": "12227-000",
        "Phone": "+55 (12) 3923-5555",
        "Fax": "+55 (12) 3923-5566",
        "Email": "luisg@embraer.com.br",
        "SupportRepId": 3,
        "Invoice": {
            "__href": "/db/Chinook/Customer/CustomerId/1/Invoice.json"
        }
    },
    {
        "__href": "/db/Chinook/Customer/CustomerId/2.json",
        "Employee": {
            "__href": "/db/Chinook/Customer/CustomerId/2/Employee.json"
        },
        "CustomerId": 2,
        "FirstName": "Leonie",
        "LastName": "K\u00f6hler",
        "Company": null,
        "Address": "Theodor-Heuss-Stra\u00dfe 34",
        "City": "Stuttgart",
        "State": null,
        "Country": "Germany",
        "PostalCode": "70174",
        "Phone": "+49 0711 2842222",
        "Fax": null,
        "Email": "leonekohler@surfeu.de",
        "SupportRepId": 5,
        "Invoice": {
            "__href": "/db/Chinook/Customer/CustomerId/2/Invoice.json"
        }
    }
]

Single Record

To access a single record in a table, use the /db/[database_id]/[table_name]/[record_id] URL.

Important

This URL only works for tables with primary keys. See Resource Types - Single Object for more info.

Example

/db/Chinook/Customer/CustomerId/1.json - get the Chinook Customer with CustomerId = 1 in JSON format:

{
    "__href": "/db/Chinook/Customer/CustomerId/1.json",
    "Employee": {
        "__href": "/db/Chinook/Customer/CustomerId/1/Employee.json"
    },
    "CustomerId": 1,
    "FirstName": "Lu\u00eds",
    "LastName": "Gon\u00e7alves",
    "Company": "Embraer - Empresa Brasileira de Aeron\u00e1utica S.A.",
    "Address": "Av. Brigadeiro Faria Lima, 2170",
    "City": "S\u00e3o Jos\u00e9 dos Campos",
    "State": "SP",
    "Country": "Brazil",
    "PostalCode": "12227-000",
    "Phone": "+55 (12) 3923-5555",
    "Fax": "+55 (12) 3923-5566",
    "Email": "luisg@embraer.com.br",
    "SupportRepId": 3,
    "Invoice": {
        "__href": "/db/Chinook/Customer/CustomerId/1/Invoice.json"
    }
}

Single Value

To access a single value from a record in a table, use the /db/[database_id]/[table_name]/[record_id]/[column_name] URL.

Example

/db/Chinook/Customer/CustomerId/14/FirstName.json - get the FirstName value from the Chinook Customer with CustomerId = 14 in JSON format:

"Mark"

Following Relations

The URL endpoints created by SlashDB can include relationships between tables. This allows you to retrieve a resource, find a relationship (i.e. a foreign key reference) and retrieve the related resource just by making another HTTP request. You can follow as many relationship as you need, even circling back to a previously encountered relationship.

The URL for a relationship typically looks like /db/[database_id]/[table_name]/[related_table_name].

Info

Within each relationship context (i.e. table) you can filter records as needed.

Examples

/db/Chinook/Customer/CustomerId/14/Invoice.html - for Customer with CustomerId = 14, get the related Invoice records.

db/Chinook/Customer/CustomerId/14/Invoice/InvoiceLine/Track/Album/Artist.html - get any Artist whose music the Customer purchased

/db/Chinook/Customer/CustomerId/14/Invoice/InvoiceDate/2013-03-01../InvoiceLine/Track/Album - get any Album purchased by the Customer after 2013-10-08

Output Document Formats

Each URL represents a specific resource. The file extension suffix in the URL specifies the request/response format of the HTTP transaction’s payload. If no extension is provided, HTML data will be returned by default.

The format of a response body can be selected by:

adding the file extension suffix to the URL, or
adding an Accept header to a request when receiving a payload.

If both the extension and the header are present in a request, then the extension takes precedence.

Responses will include a Content-Type header corresponding to the format requested.

When sending a payload (using HTTP methods PUT or POST), adding a Content-Type header to the request will control how SlashDB will interpret that content. The response body, if any, will be of the same type as the request's Content-Type.

HTML

Extension: .html or no extension

Accept Header: text/html

Receiving:

curl  "https://demo.slashdb.com/db/Chinook/Genre"

curl  "https://demo.slashdb.com/db/Chinook/Genre.html"

curl  -H "Accept: text/html" "https://demo.slashdb.com/db/Chinook/Genre"

Sending:

Sending data in HTML is not applicable.

JSON

Extension: .json

Accept Header: application/json

Receiving:

curl  "https://demo.slashdb.com/db/Chinook/Genre.json"

curl  -H "Accept: application/json" "https://demo.slashdb.com/db/Chinook/Genre"

Sending:

curl --request PUT \
  --data-binary @genre1.json \
  "https://demo.slashdb.com/db/Chinook/Genre/GenreId/1.json"

curl --request PUT \
  --header "Content-Type: application/json" \
  --data-binary @genre1.json \
  "https://demo.slashdb.com/db/Chinook/Genre/GenreId/1"

XML

Extension: .xml

Accept Header: text/xml or application/xml

Receiving:

curl  "https://demo.slashdb.com/db/Chinook/Genre.xml"

curl  -H "Accept: text/xml" "https://demo.slashdb.com/db/Chinook/Genre"

curl  -H "Accept: application/xml" "https://demo.slashdb.com/db/Chinook/Genre"

Sending:

curl --request PUT \
  --data-binary @genre1.xml \
  "https://demo.slashdb.com/db/Chinook/Genre/GenreId/1.xml"

curl --request PUT \
  --header "Content-Type: text/xml" \
  --data-binary @genre1.xml \
  "https://demo.slashdb.com/db/Chinook/Genre/GenreId/1"

curl --request PUT \
  --header "Content-Type: application/xml" \
  --data-binary @genre1.xml \
  "https://demo.slashdb.com/db/Chinook/Genre/GenreId/1"

XSD

Deprecated

SlashDB previously supported only XML schemas, using the .xsd extension. Schemas are now supported for JSON, XML, and CSV formats, using the schema URL query string parameter (modifier). Support for the .xsd extension is deprecated and will be dropped in future releases. Using the extension in the current release will automatically redirect to an XML request with the schema modifier. See Schemas for more information.

Extension: .xsd

Accept Header: text/xsd

Receiving:

curl  "https://demo.slashdb.com/db/Chinook/Genre.xsd"

curl  -H "Accept: text/xsd" "https://demo.slashdb.com/db/Chinook/Genre"

Sending:

N/A

CSV

Extension: .csv

Accept header: text/csv

Receiving:

curl  "https://demo.slashdb.com/db/Chinook/Genre.csv"

curl  -H "Accept: text/csv" "https://demo.slashdb.com/db/Chinook/Genre"

Sending:

curl --request PUT \
  --data-binary @genre1.csv \
  "https://demo.slashdb.com/db/Chinook/Genre/GenreId/1.csv"

curl --request PUT \
  --header "Content-Type: text/csv" \
  --data-binary @genre1.csv \
  "https://demo.slashdb.com/db/Chinook/Genre/GenreId/1"

Navigating Data

List of Databases

Actions

Navigation Using the Browser

List of Tables

Table Records

Single Record

Navigation Using URLs

List of Databases

List of Tables

Table Records

Single Record

Following Relations

Output Document Formats

HTML

JSON

XML

XSD

CSV