1.1 Assumptions¶

This guide was written with the following assumptions in mind. The user:

• Has a basic to moderate understanding of JSON or semi-structured data.
• Has appropriate permissions to install the software.
• Has read and write access to a data source, such as a database system.

1.2 Requirements¶

For SlamData to run in an optimal environment please see the Minimum System Requirements section.

1.3 Installation¶

Please see the Installation Section of the Administrator’s Guide for installation instructions.

2.1 - Configuration Suggestions¶

Modify the vmoptions file to adjust the Java memory heap space. JVM memory allocation varies by default based upon the JVM vendor and version. To ensure correct functionality, reserve 1GB or more of JVM heap space, increasing it based upon requirements. It is not uncommon to have more than 4GB of heap space reserved for SlamData server environments.

Some examples of where the vmoptions file can be found are as follows:

An example for reserving 4GB of JVM heap space for a server-class system is as follows:

-server
-Xms4g
-Xmx4g

The -server entry, depending on JVM vendor and version, will typically focus on longer initial load times to allow better compilation methods for faster run-time. -Xms4g immediately allocates no less than 4GB of memory and -Xmx4g allocates no more than 4GB of memory.

2.2 The Log File¶

If a user suspects that SlamData is not functioning correctly, the first step to troubleshooting is to look at the most recent log file, located as follows:

Some JVM errors can cause the JVM to stop running completely, resulting in the SlamData User Interface (UI) becoming unresponsive. Reviewing the log file should provide helpful information.

2.3 Browsers¶

The most compatible browsers with SlamData are always the most recent versions of Google Chrome and Mozilla Firefox.

Internet Explorer and Safari are both limited in functionality and some UI elements, such as Date picker, do not render properly, or at all.

3.1 Workspace Background¶

SlamData approaches analytics workflows with the metaphor of a deck or multiple decks of cards, sometimes on a Draftboard layout. A deck is built by stacking unique cards on top of one another, each card having a specific purpose, such as opening a table or collection, displaying a result set, displaying a chart, and so on.

3.2 Mount Data Source¶

In this guide the MongoDB database will be used in the examples.

Default MongoDB installations run on port 27017 and have no user authentication enabled. This guide assumes this configuration in the following instructions.

Click the New Mount icon.

A dialog will appear requesting the name and Mount type.

Enter the values below and the dialog will expand.

In the expanded dialog enter the values below and click Mount. If a parameter in the table below has no value, leave that field empty in the interface.

3.3 Creating a Database¶

• Click on the newly created server named myserver. The interface now shows the databases that reside within the database system. A new database will need to be created to follow along with the guide.

• Click on the Create Folder icon.

  A new folder will appear titled Untitled Folder.

• Hover the mouse over Untitled Folder.

• Click the Move / rename icon that appears to the right.

• Change the name from Untitled Folder to testdb and click Rename.

• Click on the newly renamed testdb folder.

3.4 Importing Example Data¶

This guide uses a data set of fictitious patient information that was randomly generated. The examples in the remaining sections will assume that the patients data set is being used.

A data set with 10,000 documents can be downloaded by following these instructions:

• Right click this link and save the file as patients. This is a 9 MB JSON file.
• If your operating system named the file something other than patients you can either rename it or you can rename it inside of SlamData once it has been uploaded.
• Ensure the SlamData UI is in testdb, and click the Upload icon.
• In the file dialog find the patients file and submit it.

As you can see, it is easy to quickly import JSON data into SlamData. Other formats, such as CSV, can also be quickly imported.

You may wish to index the newly imported patients data set. If using MongoDB refer to this section of the Developer’s Guide to increase search and query performance.

3.5 Exploring Sample Data¶

• Click on patients in the user interface.
• A dialog will appear asking the name of the new Workspace being created.
• Give the Workspace a new name and click Explore.
• You will be presented with a table showing the contents of the patients data.

Note that the data in the table is not only top level fields but also contains arrays of various types of data for each record or document.

In this instance SlamData created a new Workspace for you, created an Open Card pointing to the patients data, then stacked a Preview Table Card on top of the Open Card.

You can verify this by clicking on the left dots (grippers) on the left side of the screen and seeing the top most card slide to the right. The card now displayed is the Open Card. This determines which table or collection is used by the cards following it.

• Click on the right grippers to go back to the Preview Table Card.

Click on the browse arrows at the bottom to scroll through the pages of data.

Click on the Zoom Out icon in the upper left of the interface to return to the database view.

3.6 Querying Sample Data¶

• Create a new workspace by clicking on the Create Workspace icon.
• Select the Query Card.
• Replace the provided query text with the query below:

SELECT
  last_name || ", " || first_name AS Name,
  city as City,
  state as State,
  codes[*].code AS Code,
  codes[*].desc AS Description
FROM `/myserver/testdb/patients`

Notice that we are concatenating two fields (last_name and first_name), as well as analyzing each document within the codes array and fetching the code and desc fields from each of those documents.

• Select Run Query in the bottom right.
• Click the right grip.
• Select the Preview Table Card to see the results.
• Click the Zoom Out icon to return to the database view.
• Optionally rename the Untitled Workspace that was created for this workflow.

3.7 Searching Data¶

SlamData has several very powerful ways of finding the data you need. In the following example, you will use the Search Card.

• Select the Create Workspace icon.
• Select Open Card.
• Locate the patients entry in your database and select it.
• Click and drag the right-hand grip and slide it to the left.

The following card types will be presented:

Notice how the cards are blue and gray. The blue cards are those that can be created directly after the Open Card. Gray cards are those cards that cannot be used following the previous card.

• Select the Search Card.

A new Search Card will appear in the UI. The search string appears simple but has some very powerful search features.

• Type the word Austin and either drag the right grip bar to the left, or simply click on the right grip bar.
• Select the Preview Table Card.

Depending on the performance of your system and database it may take several seconds before the results are displayed. Keep in mind that SlamData is searching the patients collection that we imported into the database system, and that indexes can significantly boost performance for searches.

Once the results appear, you can browse them just like you did earlier in the Preview Table Card with the controls in the bottom left of the interface.

Did you notice that in the search string earlier we did not specify which field we wanted to search? That is part of the power of SlamData. Relatively non-technical users can use SlamData to search all of their data sources with little (or even no) knowledge in advance of the data stored within.

Of course when searching all available fields for the search string it is going to take longer than if we were to explicitly define which field. Let’s go back to the search card by dragging the current card to the right again, or single-click on the left grip.

Let’s search for any patients currently living in the city of Dallas.

• Type the string city:Dallas and either drag the right grip bar to the left, or simply click on the right grip bar.
• View the results in the Preview Table Card again.

The results should have appeared much faster than the previous search because we told SlamData to only look at the city field.

We can also search on non-string values such as numbers. Let’s find all of the patients who are between the ages of 45 and 50:

• Go back to the Search Card.
• Enter the string age:>=45 age:<=50.
• View the results in the Preview Table Card again.

As one last example let’s see how we can mix and match different types. We want to know how many males over the age of 50 used to live in California.

• Go back to the Search Card.
• Enter the string previous_addresses:"[*]":state:CA age:>50 gender:=male.
• View the results.

3.8 - Downloading Data¶

This workspace can be adjusted to allow a user to download the results of the search after the search is complete.

• Click the right gripper to stack a new card on top of the Preview Table Card.
• Select Setup Download.
• Select either C;S;V (CSV) or {JS} (JSON) format for the download.
• Click the right gripper to stack a new card on the deck.
• Select Show Download.
• Select the Download button to download the data.

You have now entered search criteria, browsed the results and downloaded the results in a CSV or JSON format.

4.1 Introduction to Cards¶

Cards each have a distinct purpose and typically provide a single, unique action that can often be combined with the cards before and after it to create a workflow. This section describes the types of cards and the purpose of each. The cards are described in alphabetical order.

4.2 - Cache Card¶

4.3 - Open Card¶

4.4 - Preview Table Card¶

4.5 - Query Card¶

4.6 - Search Card¶

4.7 - Setup Chart Card¶

4.8 - Setup Dashboard Card¶

4.9 - Setup Download Card¶

4.10 - Setup Form Card¶

4.11 - Setup Markdown Card¶

4.12 - Setup Variables Card¶

SlamData.embed({
  deckPath: "/server/db/collection/MyWorkspace.slam/",
  deckId: "deckid...abc...123...",
  // An array of custom stylesheets URLs can be provided here
  stylesheets: [],
  // The variables for the deck(s), you can change their values here:
  vars: {
    "deckid...abc...123...": {
      "state": "CO",
      "city": "DENVER"
    }
  }
});

SELECT *
FROM `/server/db/collection`
WHERE _id = :myoidvar

SELECT *
FROM `/server/db/collection`
WHERE sensor IN :sensors

SELECT *
FROM `/server/db/collection`

SELECT *
FROM :mypath

4.13 - Show Chart Card¶

4.14 - Show Download Card¶

4.15 Show Form Card¶

4.16 - Show Markdown Card¶

4.17 - Troubleshoot Card¶

1.1 Minimum System Requirements¶

• Minimum memory

  • 2 GB memory
  • An additional 25 MB is required for each active user

• Disk

  • 300 MB for a basic installation
  • Additional space varies based upon Workspace size, cached queries, and so on

• Java

  • Java 1.8 or newer
  • Windows and Mac OS versions of SlamData with installers include Java
  • Linux requires a separate Java installation

• Browsers

  • The most compatible browsers with SlamData are always the most recent versions of Google Chrome and Mozilla Firefox
  • Internet Explorer and Safari are both limited in functionality and some UI elements, such as Date picker, do not render properly, or at all

• Target data sources (for analytics)

  • Apache Spark 2.1 or newer
  • Couchbase 4.5.1 or newer
  • MarkLogic 8 or newer
  • MongoDB 2.6 or newer

SlamData Community Edition uses a file called quasar-config.json to store server configuration data.

SlamData Analyst Edition and SlamData Advanced Edition store configuration data in a metastore database. This should not be confused with target data sources. The options for storing server configuration data are as follows:

• Metastore data sources

  • Java H2 (included with SlamData)
  • PostgreSQL 9.x (must be installed and configured separately)

1.2 Obtaining SlamData¶

npm install bower -g

npm install -g gulp

git clone https://github.com/slamdata/slamdata.git
cd slamdata

bower install
npm install

npm i && bower i && gulp make && gulp bundle && gulp less

1.3 Starting SlamData¶

SlamData is comprised of a front-end interface and a back-end analytics engine. Starting the SlamData application will start both.

Server started listening on port 20223
Press Enter to stop.

_JAVA_OPTIONS="-Xms1G -Xmx4G"

export SD_OPTS="\
-Dlicense_key=ABCDE-12345-ABCDE-12345-ABCDE \
-Dlicense_email=myemail@example.com \
-Dlicense_full_name=\"My Name\" \
-Dlicense_registered_to=\"Name Registered To\" \
-Dlicense_company=\"My Company Name\" \
-Dlicense_street=\"123 Anywhere Street, Suite A1\" \
-Dlicense_tel_number=3035551212 \
-Dlicense_fax_number=NA \
-Dlicense_city=Boulder \
-Dlicense_zip=80302 \
-Dlicense_country=US"

export _JAVA_OPTIONS="$_JAVA_OPTIONS $SD_OPTS"

java -jar quasar.jar --content-path public

2.1 Data Sources¶

Supported data sources are listed in the following sections. As new target data sources are released, they will be listed below.

To connect to data source click on the Mount icon in the upper right.

A mount dialog will be presented, as shown below.

Enter a name for the data source mount. This name is used in the SlamData User Interface (UI) as well as SQL² query paths.

Click the Mount button to mount the database in SlamData.

2.2 Mount Options¶

The mount dialog will display the appropriate fields based upon the mount type selected. For each data source that SlamData supports, a section below describes the options available.

CREATE PRIMARY INDEX ON default;
CREATE INDEX default_type_idx ON `default`(type);

2.3 Several Mounts¶

After mounting several data sources, the SlamData UI might look like the following image. In this image, there are two separate mounts named aws and macbook, the latter representing a locally mounted data source.

2.4 SQL² View¶

SQL² Views are covered in detail in the SlamData Developer’s Guide.

2.5 Enabling SSL¶

If you have difficulty following the steps below, you may also view the SSL tutorial video.

If a data source connection supports SSL encryption, that is to say encryption between a client and server such as SlamData and the data source, additional configuration will be required.

The backend engine of SlamData is written in Scala and executes within a Java Virtual Machine (JVM). To enable SSL encryption, several options must be passed to the JVM when running SlamData. SlamData simplifies this by allowing these options to be listed in a text file that the SlamData launcher will reference when executed. The file location for each operating system is shown in the following table.

There are two important options that must be passed to the JVM at startup to enable SSL. These options are shown in the table below and point the JVM to a Java Key Store (JKS).

Example values for these two options could be as shown in the code below.

-Djavax.net.ssl.trustStore=/users/me/ssl/truststore.jks
-Djavax.net.ssl.trustStorePassword=mySecretPassword

This guide does not provide exhaustive steps to create a Java Key Store in every scenario, but the following simple example should be helpful.

Let’s consider a data source hosted with a service provider. That service provider makes a signed (or self-signed) certificate available so that the data source can connect securely using SSL. Using the JKS configuration described above, the your_provider.crt text file could be created as follows.

1. Import the certificate into the Java trust store, as follows.

keytool -import -alias "your_providers_name" -file your_provider.crt \
-keystore /users/me/ssl/truststore.jks -noprompt -storepass mySecretPassword

2. Ensure that the appropriate changes have been made to the JVM options file referenced above.
3. Restart SlamData so it reloads the JVM options file and picks up the new certificate in the JKS.
4. Mount the data source with SSL as shown in the following image. This example uses MongoDB.

3.1 Community Edition Configuration File¶

The SlamData configuration file allows an administrator to change settings, such as the port number SlamData listens on, the mounts available, and so on. The location of the configuration file depends upon the operating system being used, as shown in the table below.

An example configuration file for SlamData Community Edition is shown below.

{
  "server": {
    "port": 8080,
    "ssl": {
      "enabled": true,
      "port": 9090,
      "cert": "<base64 encoded pkcs12 cert file>"
    }
  },

  "mountings": {
    "/aws/": {
      "mongodb": {
        "connectionUri": "mongodb://myUser:myPass@aws-box.example.com:27017/admin"
      }
    },
    "/macbook/": {
      "mongodb": {
        "connectionUri": "mongodb://localhost:27017"
      }
    }
  },
}

3.2 Advanced Edition Configuration File¶

SlamData Advanced Edition has additional configuration parameters to setup security, including the authentication, auditing and metastore directives.

An example configuration file for SlamData Advanced Edition might appear as follows.

{
  "server": {
    "port": 8080,
    "ssl": {
      "enabled": true,
      "port": 9090,
      "cert": "<base64 encoded pkcs12 cert file>"
    }
  },

  "authentication": {
    "openid_providers": [
      {
        "issuer": "https://accounts.google.com",
        "client_id": "123...googleusercontent.com",
        "display_name": "Google",
      },
      {
        "issuer": "https://accounts.google.com",
        "client_id": "456...789.apps.googleusercontent.com",
        "display_name": "OAuth 2.0 Playground"
      }
    ]
  },
  {
    "display_name": "Our Company OP",
    "client_id": "123455976",
    "openid_configuration": {
      "issuer": "https://op.ourcompany.com",
      "authorization_endpoint": "https://op.ourcompany.com/authorize",
      "token_endpoint": "https://op.ourcompany.com/token",
      "userinfo_endpoint": "https://op.ourcompany.com/userinfo",
      "jwks": [
        {
          "kty": "RSA",
          "kid": "1234",
          "alg": "RS256",
          "use": "sig",
          "n": "2354098udw...2957835lkj"
        },
        {
          "kty": "RSA",
          "kid": "5678",
          "alg": "RS256",
          "use": "sig",
          "n": "skljhdfiugy...39587dlkjsd"
        }
      ]
    }
  },

  "auditing": {
    "log_file": "/aws/logdb/slamdata-logs"
  },

  "metastore": {
    "database": "<h2 config | postgresql config>"
  }
}

The following example quasar-config.json file allows SlamData users to use Postgres instead of H2 as the metastore:

"metastore": {
  "database": {
    "postgresql": {
      "host": "192.168.99.100",
      "port": 5432,
      "database": "slamdata",
      "userName": "postgres",
      "password": "postgres"
    }
  }
}

4.1 Security Overview¶

SlamData Advanced Edition controls user security through the use of tokens, permissions, groups, actions and types. Each of these is defined in the table below.

4.2 Initializing the SlamData Metastore¶

SlamData Advanced Edition uses a metastore for user security. Before SlamData Advanced Edition can be started, the metadata store must be initialized and initial administrator users defined. The administrator users are added to a group having complete and unrestricted access to the system allowing them to provision additional groups and roles as needed.

To initialize the metadata store, run the bootstrap command and provide the name of the administrator group and e-mail addresses of initial members, as shown in the following example.

java -jar quasar.jar bootstrap --admin-group <name> --admin-users user1@example.com[,user2@example.com,...]

4.3 Authentication¶

SlamData Advanced Edition adds support for authenticated requests via the OpenID Connect protocol. A request to any SlamData or SlamData Advanced Edition API may be authenticated. If no credentials are included in a request, it is considered unauthenticated (or “anonymous”) and may fail if the system is not configured to allow anonymous access for the given request.

4.4 Authorization¶

SlamData Advanced Edition adds support for authorization of service requests. Permissions for a request are derived from the union of permission tokens provided in the X-Extra-Permissions header and those configured for the authenticated user and anonymous user. Permissions are defined as an operation, its type, and a filesystem resource path. A permission token grants a set of permissions.

The available operations and types are as follows.

Type: Content, Structural, Mount

Operation: Add, Read, Delete, Modify

A permission on a parent resource is sufficient to authorize an action on a resource granted the nature and type of the operation are the same.

A 403 Forbidden is returned by the server when a request does not have sufficient permissions to perform the associated actions.

The X-Extra-Permissions header is formatted as follows.

X-Extra-Permissions: [token1],[token2]

4.5 Auditing¶

When a log file is specified in the configuration file, all filesystem operations will be logged to that file. SlamData Advanced Edition logs the operations as data in the filesystem where the path is located. This means that it is then possible to use SlamData Advanced Edition to analyze the log data.

5.1 - Group Endpoint¶

GET /security/group/<path>

• Retrieves information about this group. The result of the query will depend upon your permissions according to the rules described below.
• If you have READ content group permission on this group, then your view is unrestricted. (all fields are present).
• If you have READ structural group permission on this group, then you can know of the existence of this group and all of its sub-groups. (subGroups field is present in response).
• If you have ANY OTHER group permission on this group, you can know of the existence of this group, but nothing else. (response is empty).
• If you have READ content group permission on one of this group’s sub-groups, then you can see that subgroup as well as any of its own subgroups. You can see all members of that group and sub-groups. (allMembers and subGroups fields are present in response).
• If you have READ structural group permission on one of this group’s sub-groups, then you can see that subgroup as well as any of its own sub-groups. You cannot see any of the members of those groups however. (subGroups field is present in response).
• If you have ANY OTHER group permission on one of this group’s sub-groups, then you can see that subgroup.

These rules are cumulative, so if more than one rule applies, you will see the combined result. If none of the rules apply, the query will result in a 403 Forbidden. If certain fields do not apply to your view of this group, they will be omitted in order to clearly convey that they are not necessarily empty, you just don’t have permission to see anything related to that field.

• <path> is the path of the group in the group hierarchy

Response:

The response body will vary depending on the rules outlined above. If you have some relevant permission as outlined above and the group does not exist, the response will be a 404 Not Found.

{
  "members": ["<user_email>", "..."],
  "allMembers": ["<user_email>", "..."],
  "subGroups": ["<group_path>", "..."],
}

• members All users are explicitly a member of this group.
• allMembers All users are explicitly and implicitly a member of this group. Implicit members of a group refer to the users that are explicit members of any of the sub-groups of this group.
• subGroups All descendants of this group in the group hierarchy.

Example:

Given the following groups exist in the system:

/corporate -> “Alice” /corporate/engineering -> “Bob” /corporate/engineering/software -> /corporate/engineering/software/scala -> “Marcy” /corporate/engineering/hardware -> (“Tom”, “Beth”)

GET /security/group/corporate/engineering will return the following:

{
    "members": ["bob@example.com"],
    "allMembers": [ "bob@example.com",
        "marcy@example.com",
        "tom@example.com",
        "beth@example.com"
    ],
    "subGroups": [ "/corporate/engineering/software",
        "/corporate/engineering/software/scala",
        "/corporate/engineering/hardware"
    ]
}

POST /security/group/<path>

Creates a new empty group. If any of the parent groups do not exist yet, they will be created.

Requires ADD or MODIFY structural group permission.

Response:

If you have adequate permissions and the group already exists, will return a 400 Bad Request.

PATCH /security/group/<path>

Add or remove users of a group.

Requires ADD content group permission to add users. Requires DELETE content group permission to remove users. Alternatively, the MODIFY content group permission is sufficient to add and/or remove users.

Request:

{
  "addUsers": ["<user_email>"],
  "removeUsers": ["<user_email>"]
}

Response:

If you have adequate permissions, but the group does not exist, the response will be a 404 Not Found. If a user found in the removeUsers field was not actually a member of the group, the request will succeed nevertheless and simply ignore that user.

DELETE /security/group/<path>

Delete this group and all of its sub-groups. All permissions associated with this group and subgroups as well as shared by this group and subgroups will immediately become invalid.

Requires DELETE or MODIFY structural group permission.

Response:

If you have adequate permissions, but the group does not exist, the response will be a 404 Not Found

5.2 - Authority Endpoint¶

GET /security/authority

Returns all permissions granted to you.

Response:

[<permission>]

5.3 - Permission Endpoint¶

GET /security/permission[?transitive]

Returns all permissions granted by you. If the transitive query param is supplied, will also return all permissions which were derived from your own.

We may add query parameters in the future in order to filter the result set.

Response:

[<permission>]

GET /security/permission/<permission_id>

Retrieve a permission by its unique identifier. You may only retrieve information about permissions shared with you or by you.

If the permission does not exist or you do not have adequate permission to see it, the response will be a 404 Not Found.

Response:

<permission>

GET /security/permission/<permission_id>/children[?transitive]

Retrieve all permissions that were directly derived from this permission. If the transitive query param is supplied, will also include permissions which were indirectly derived. You may only retrieve information about permissions shared with you or by you.

If the permission does not exist or you do not have adequate permission to see it, the response will be a 404 Not Found.

Response:

[<permission>]

POST /security/permission

Grant new permissions to a given set of users and/or groups.

Request:

{
  "subjects" : ["<user_id>", "<group_id>", "..."],
  "actions": []
}

• user_id is a email prefixed with the “user” string such as user:bob@example.com representing the users to whom you wish to grant permissions. Users do not need to exist in the system at the time the permission is granted. When a user first logs into the system, they will be able to perform any action associated with permissions granted to their email.
• group_id a path prefixed with the “group” string such as group:/engineering/backend. Groups DO need to exist in the system prior to granting them a permission. Providing a group path that points to a group that does not yet exist in the system will result in a 400 Bad Request and no new permissions will have been granted to users or groups.
• actions The actions that the new permissions will allow the subjects to perform. All actions must be the same or a subset of actions found in your permissions. If that is not the case a 400 Bad Request with an appropriate message will be returned and no new permissions will have been granted to users or groups.

Although all fields accept arrays, a permission is only ever granted to ONE subject to perform ONE action. Thus, many permissions will be created and returned by this endpoint.

Response:

[<permission>]

DELETE /security/permission/

Revoke a permission. In order to revoke a permission, you must have a permission which is a source of authority for the permission you wish to revoke.

Refer to the top-level api description for explanation on the process of revoking.

If the permission does not exist or you do not have adequate permission to see it, the response will be a 404 Not Found. If you attempt to revoke one of your own permissions, the response will be a 400 Bad Request.

5.4 - Token Endpoint¶

The following is the JSON representation of a token.

{
  "id": "<token_id>",
  "secret": "<token_hash>",
  "name": "<name>",
  "grantedBy": ["<token_id>", "<user_id>", "<group_id>", "..."],
  "actions": [{
    "operation": "ADD|READ|MODIFY|DELETE",
    "resource": "<filesystem_path>|<group_path>",
    "accessType": "Structural|Content|Mount",
  }]
}

• secret is a cryptographically secure string whose possession allows you to perform the action associated with the token.
• name an optional field that may or may not have been provided upon creation of the token.
• is a string identifier prefixed by the “token:” string
• an email address prefixed with the “user:” string
• a group path prefixed with the “group:” string

GET /security/token

List tokens that you have created. Does not list tokens that were created by others based on your authority.

The JSON representation of the tokens does not contain the secret field for this endpoint in order to reduce the chance of the secret leaking. The secret can be retrieved by using the id endpoint.

Response:

[<token>]

GET /security/token/<id>

Retrieve token for a given id.

You may only retrieve information about a token that you created. If the token does not exist or was not created by you, the response will be a 404 Not Found.

Response:

<token>

POST /security/token

Create a new token granting the capability to perform the given actions. All actions must be a subset of your own capabilities. If the later condition is not satisfied, a 400 Bad Request will be returned.

Request:

{
  "name": "",
  "actions": []
}

• name is an optional field

Response:

<token>

DELETE /security/token/<id>

Delete a token. In order to delete a token, you must have a permission which is a source of authority of the token. If the token does not exist or was not created by you, a 404 Not Found will be returned.

GET /security/oidc/providers

This endpoint allows clients to obtain the list of configured OpenID Providers (OPs). Responses will be a JSON array of configurations similar to the following.

Response:

[
  {
    "display_name": "Google",
    "client_id": "sdf9......dflkj",
    "openid_configuration": {
      "issuer": "https://accounts.google.com",
      "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
      "token_endpoint": "https://www.googleapis.com/oauth2/v4/token",
      "userinfo_endpoint": "https://www.googleapis.com/oauth2/v3/userinfo",
      "jwks": [
        {
          "kty": "RSA",
          "alg": "RS256",
          "use": "sig",
          "kid": "1195d......6abd",
          "n": "qy5D0......tJRJY02Qt0UKzJ2OquiPw",
          "e": "AQAB"
        },
        {
          "kty": "RSA",
          "alg": "RS256",
          "use": "sig",
          "kid": "b0a61.....9ba8575712",
          "n": "rvhjUe0..........n2IRNM8S8iJ36w",
          "e": "AQAB"
        }
      ]
    }
  },
  {
    "display_name": "Our Company OP",
    "client_id": "123455976",
    "openid_configuration": {
      "issuer": "https://op.ourcompany.com",
      "authorization_endpoint": "https://op.ourcompany.com/authorize",
      "token_endpoint": "https://op.ourcompany.com/token",
      "userinfo_endpoint": "https://op.ourcompany.com/userinfo",
      "jwks": [
        {
          "kty": "RSA",
          "kid": "1234",
          "alg": "RS256",
          "use": "sig",
          "n": "2354098udw...2957835lkj"
        },
        {
          "kty": "RSA",
          "kid": "5678",
          "alg": "RS256",
          "use": "sig",
          "n": "skljhdfiugy...39587dlkjsd"
        }
      ]
    }
  }
]

1.1 Purpose¶

The purpose of this Developer’s Guide is to walk a software developer through SlamData from installation through to a completed project. The goal is to provide a step-by-step process that a developer can follow, including sample data, that is repeatable with other data sets and environments.

1.2 Introduction¶

SlamData is both an Open Source Software project and a commercially available Visual Analytics platform for multidimensional data (including two-dimensional RDBMS data). SlamData provides the ability to query all of your data, in any form, in any location with a single solution. This is achieved with some of the following features of SlamData:

• Patented multidimensional relational technology, allowing SlamData to communicate with any data source in any data format. This includes not only historical two-dimensional data such as RDBMS in rows and columns, but also deeply nested, semi-structured data such as JSON and XML.
• Ability to understand schemas dynamically, resulting in absolutely no requirement to map field types from one technology to another. This also allows SlamData to use both field values and the schema as data. This is not possible with other NoSQL -> relational solutions.
• A fully generalized database backend technology, providing a reliable and ANSI compatible superset of SQL called SQL² that runs on top of any supported data source. There is no need to learn yet another proprietary query language.
• Fully embeddable solution that merges seamlessly with your own applications providing a consistent look and feel while providing significant and immediate value out of the box.
• Easy to use search capabilities for non-technical users. Search for a key word, value or any other data type without knowing where it is or in which format.
• Visually appealing charts (eCharts from Baidu) that can be customized and natively understand nested data.
• Ability to secure data in a multi-tenant environment through OpenID Connect and OAuth 2.0.

1.3 Assumptions¶

This guide was written with the following assumptions in mind. The reader is a developer that:

• Has a basic to moderate understanding of SQL.
• Has a basic to moderate understanding of JSON.
• Has a basic to moderate understanding of HTML web applications.
• Can perform basic navigation of a data source, such as a database system.
• Has appropriate permissions to install relevant software.

1.4 Requirements¶

For SlamData to run in an optimal environment see the Minimum System Requirements section.

1.5 Installation¶

Instructions for installing SlamData can be found here.

1.6 Starting SlamData¶

Instructions for starting SlamData can be found here.

Once SlamData is running then continue to Section 2.

2.1 Interface Navigation¶

The image below shows the Home screen after starting SlamData Community Edition. Note the numbers and their descriptions following the image.

2.2 Workspaces, Decks and Cards¶

Before we start looking at our data we need to discuss how to interact with it. This is done through the use of a Workspace. A Workspace is the primary method that users interact with data within SlamData. A Workspace in turn is comprised of cards, and decks of cards.

• Root Deck - Each Workspace must have a Root Deck in which all other unit types are stored. A Root Deck is always present in a Workspace but never visible.

• Deck - Each deck contains at least one or more cards that each perform a specific action and build upon each other. Decks can be mirrored which allows easy creation of a new target deck that starts with the same functionality as the origin deck. Changes in each deck, up to the point where they were mirrored, will impact each other.

• Draftboard Card - A special card type that creates a visual area to arrange multiple decks.

• Card - A unit that performs a distinct action. Examples include:

  • Query Card.
  • Search Card.
  • Preview Table Card.
  • and more ...

A visual example of the allowable nesting follows:

Don’t worry! You won’t need to know any of this until section 3, and by then we will take you through it step-by-step.

2.3 Creating a New Mount¶

In this guide the MongoDB database will be used in the examples. As such, the reader should download and run the latest stable version of MongoDB.

Default MongoDB installations run on port 27017 and have no user authentication enabled. This guide assumes this configuration in the following instructions.

Click the New Mount Icon.

A dialog will appear requesting the name and Mount type.

Enter the values below and the dialog will expand.

In the expanded dialog enter the values below and click Mount. If a parameter in the table below has no value, leave that field empty in the interface.

2.4 Creating a Database¶

• Click on the newly created server named devguide. The interface now shows the databases that reside within the database system. A new database will need to be created to follow along with the guide.

• Click on the Create Folder icon.

  A new folder will appear titled Untitled Folder.

• Hover the mouse over the new Untitled Folder folder.

• Click the Move / rename icon that appears to the right.

• Change the name from Untitled Folder to devdb and click Rename.

• Click on the newly renamed devdb folder.

The interface should now look like this:

So far in this guide you’ve installed SlamData, mounted a database and created and renamed a folder. Good progress. Let’s now get some data into the database and start exploring.

2.5 Importing Example Data¶

This guide uses a data set of fictitious patient information that was randomly generated. The reader can use any data set they wish, but the examples in the remaining sections will assume the patients data set is being used.

You can download a data set with 10,000 documents by following these instructions:

• Right click this link and save the file as patients. This is a 9 MB JSON file.
• If your operating system named the file something other than patients you can either rename it or you can rename it inside of SlamData once it has been uploaded.
• Ensure that the SlamData UI is in devdb, and click the Upload icon.
• In the file dialog find the patients file and submit it.
• After successful upload a new collection should appear in the UI as follows:

As you can see, it is easy to quickly import JSON data into SlamData. Other formats, such as CSV, can also be quickly imported.

use devdb
db.patients.createIndex({first_name:1})
db.patients.createIndex({middle_name:1})
db.patients.createIndex({last_name:1})
db.patients.createIndex({city:1})
db.patients.createIndex({county:1})
db.patients.createIndex({state:1})
db.patients.createIndex({zip_code:1})
db.patients.createIndex({street_address:1})
db.patients.createIndex({height:1})
db.patients.createIndex({weight:1})
db.patients.createIndex({age:1})
db.patients.createIndex({gender:1})
db.patients.createIndex({last_visit:1})
db.patients.createIndex({previous_visits:1})
db.patients.createIndex({previous_addresses:1})
db.patients.createIndex({codes:1})
db.patients.createIndex({"codes.code":1})
db.patients.createIndex({"codes.desc":1})

2.6 Exploring Data¶

To simply look around and explore data, you can click on any file (collection) that you see. Start by clicking on the patients file.

You’ll be prompted to provide a name for a new Workspace. A Workspace is how users interact with the actual data within the database. Let’s start by calling this My First Test and clicking Explore.

Once you click Explore, the following screen should appear:

Feel free to click around on the browse arrows at the bottom to flip through the pages of data. It’s easy to get an idea of the schema of this data set by looking at the top row. In this case you can also see that the codes field is not actually a simple field but an array of other documents! Each of those documents in turn have a code and desc field.

Any changes made within a Workspace are saved automatically. At any time the user may zoom out of the current window.

2.7 Searching Data¶

Viewing and browsing the data is helpful but data becomes less useful if you can’t find what you’re looking for. SlamData has two very powerful ways of finding the data you need. One is the Search Card and the other is the Query Card. We’ll start with the Search Card.

• Click the Flip Card Icon (#2 in the previous image).

You’ll see the following options on the back of that card:

• Click on Delete card.

The UI will now show the only remaining card in the deck which is the Open Card. This card allows you to select which collection you wish to operate on with subsequent cards. Let’s leave this card in place.

• Click and drag the right-hand grip and slide it to the left.

You’ll be presented with the following card types to choose from:

Notice how the cards are different colors. Blue cards are those that can be created directly after the Open Card. Light gray cards are those cards that cannot be used following the previous card.

• Select the Search Card.

A new Search Card will appear in the UI. The search string appears simple but has some very powerful search features within.

• Type the word Austin and either drag the right grip bar to the left, or simply click on the right grip bar.
• Select the Preview Table Card.

Depending on the performance of your system and database it may take several seconds before the results are displayed. Keep in mind that SlamData is searching the patients collection that we imported into the database system, and that indexes can significantly boost performance for searches.

Once the results appear, you can browse them with the controls in the bottom left of the interface.

Did you notice that in the search string earlier we did not specify which field we wanted to search? That is part of the power of SlamData. Relatively non-technical users can use SlamData to search all of their data sources with little (or even no) knowledge in advance of the data stored within.

Of course when searching all available fields for the search string it is going to take longer than if we were to explicitly define which field. Let’s go back to the search card by dragging the current card to the right again, or single-click on the left grip.

Let’s search for any patients currently living in the city of Dallas.

• Type the string city:Dallas and either drag the right grip bar to the left, or simply click on the right grip bar.
• View the results in the Preview Table Card again.

The results should have appeared much faster than the previous search because we told SlamData to only look at the city field.

We can also search on non-string values such as numbers. Let’s find all of the patients who are between the ages of 45 and 50:

• Go back to the Search Card.
• Enter the string age:>=45 age:<=50.
• View the results in the Preview Table Card again.

As one last example let’s see how we can mix and match different types. We want to know how many males over the age of 50 used to live in California.

• Go back to the Search Card.
• Enter the string previous_addresses:"[*]":state:CA age:>50 gender:=male.
• View the results.

See the table below for some helpful query examples:

As you can see even users with no knowledge of SQL² can perform powerful searches within SlamData!

2.8 Querying Data with SQL²¶

In addition to the Search Card, SlamData provides a Query Card that allows users to execute ANSI-compatible SQL queries on top of any data source, including NoSQL databases! This is accomplished by using SlamData’s SQL² dialect, which is a superset of SQL that allows dynamic modeling and querying of deeply nested, semi-structured data.

Using the same dataset we are going to perform queries, moving from basic queries to more advanced queries. Let’s start off by cleaning up our Workspace.

• Go to the Preview Table Card.
• Flip it over.
• Click on Delete card.

This should take you to the Search Card.

• Flip it over.
• Click on Delete card.

This should take you to the Open Card. We will be using full path names in the queries we will write, and Query Cards do not use the Open Card so let’s delete that one as well.

• Flip it over.
• Click on Delete card.
• Create a new Query Card.

The UI now presents the Query Card. Within this card users can enter simple or very long and complex SQL² queries against one, two or more collections.

• Type in the following query:

SELECT *
FROM `/devguide/devdb/patients`

Notice how the path to the dataset is surrounded by back-ticks (`) not apostrophes (')

• Select Run Query in the bottom right.
• Click the right grip.
• Select the Preview Table Card to see the results.
• Slide back to the Query Card.
• Type in or paste the following query:

SELECT
    first_name,
    last_name
FROM `/devguide/devdb/patients`
WHERE
    state="TX" AND
    city="DALLAS"

Note that the query can span multiple lines, and that strings are surrounded by quotation marks (") on both ends. This is a requirement for all string data types.

• Select Run Query in the bottom right.
• Slide back to the Preview Table Card to see the results.
• Slide back to the Query Card.

Let’s now create a query that formats the results a little better.

• Type in or paste the following query:

SELECT
    last_name || ',' || first_name AS Name,
    city AS City,
    zip_code AS Zip
FROM `/devguide/devdb/patients`
WHERE
    state="TX"
ORDER BY zip_code ASC

• Select Run Query in the bottom right.
• Slide back to the Preview Table Card to see the results.

Notice in this query we are concatenating the last_name and first_name fields together, separated by a comma. The comma itself is surrounded by apostrophes (') because it is a single character. If it was more than one character it would be a string and would require full quotation marks around it.

We have also given the results some aliases to display rather than the actual field names.

Finally, we are ordering (ORDER BY) the results in ascending (ASC) order based on the zip_code field.

The results table should now look similar to the following image:

Up to this point we have been using SQL² to query simple top-level fields, or those fields which are not nested. We know from previous examples that this data set stores nested data in the codes array, but it also contains previous_addresses and previous_visits arrays.

Let’s find out the total number of male and female patients from each state that have an illness related to an ulcer. This will require using the flattening operator ([*]) so SlamData can examine all of the documents in the codes array.

• Slide to the Query Card.
• Type or paste the following query:

SELECT
    state AS State,
    gender AS Gender,
    COUNT(*) AS Count
FROM `/devguide/devdb/patients`
WHERE
    codes[*].desc LIKE "%ulcer%"
GROUP BY state, gender
ORDER BY COUNT(*) DESC
LIMIT 20

• Select Run Query in the bottom right.
• Slide to the Preview Table Card to see the results.

SQL² allows for very complex queries. You can find out more by reviewing the SQL² Reference. Additional features include using the JOIN command to combine data from two or more tables, utilizing variables within queries (as explained in Section 3), using standard math operations, retrieving not only field values but also field names dynamically, and much more.

Now that you have a good idea of what can be accomplished with SQL² queries, let’s create some forms that your users can interact with. These forms can drive the results of the charts we’ll use for visualization, which makes it easy for your users to find, report and chart complex data without understanding the mechanics behind it!

3.1 Static Markdown Forms¶

We will start this section with a new Workspace. You can leave the existing Workspace alone or you can delete it if you wish.

To (optionally) delete the existing Workspace:

• If you are still in the Workspace, click on the zoom-out icon.
• Locate the My First Test Workspace and hover your mouse over it.
• Click on the trash can icon that appears to the right.

We’ll create a new Workspace and call it Average Weight by City.

• Click the Create Workspace icon in the upper right.
• Select the Setup Markdown Card.

This step is necessary so that the Workspace is saved and we can go back to rename it soon.

• Create a Show Markdown card directly after the Setup Markdown Card.
• Zoom back out to the database view.

Let’s rename the Workspace now so it’s obvious that we are working with it.

• Hover over the new Workspace labeled Untitled Workspace.slam.
• Click the Move / rename icon to the right.
• Replace Untitled Workspace with Average Weight by City and click Rename.
• Click on the Average Weight by City.slam Workspace again.

Ensure that you are in the Setup Markdown Card.

SlamData uses a specific form of Markdown sometimes referred to as SlamDown. Markdown allows a user to format text with a few simple syntax rules. SlamData’s version also allows UI elements (such as drop downs, radio buttons and check boxes) to be dynamically populated from the results of queries.

Let’s first show some examples of what the Markdown forms can do. Paste the following text into the card:

# Heading 1

## Heading 2

### Text formatting

* Here is an unnumbered list.
* You can have _emphasized_ and **bold** text.

1. Here is a numbered list.
2. Here is the second entry with ```inline formatting```

Paragraphs are separated by
an empty line.

This is another new paragraph.

> You can also have some nice
> block quote areas.

You can also have fenced code blocks like this:

```
SELECT * FROM `/devguide/devdb/patients`
WHERE
  first_name = "Sue"
```

### Interactive Elements

#### Input Fields

name = ____ (Sue)

numberOnly = #____ (1984)

#### Selectors

city = {Austin, Dallas, Houston}

favoriteColor = (x) red () blue () green

computers = [] PC [x] Mac [x] Linux

beginDate = ____-__-__

stopTime = __:__

fullDateTime = ____-__-__ __:__

• Select Run Query in the bottom right.
• Click over to the Show Markdown Card to view the results.

Notice how much control you have over the presentation of the information. You can also include links and images inside of Markdown as well. For a full description of all fields and their behavior see the SlamDown Reference.

• Click back to the Setup Markdown Card.

Replace the contents with something more useful and appropriate to our use case:

## General Patient Information

There are !`` SELECT COUNT(*) FROM `/devguide/devdb/patients` `` patients

_Average_ age: !`` SELECT AVG(age) FROM `/devguide/devdb/patients` ``

The *Heaviest* patient: !`` SELECT MAX(weight) FROM `/devguide/devdb/patients` `` pounds

The **Shortest** patient: !`` SELECT MIN(height) FROM `/devguide/devdb/patients` `` inches

• Select Run Query in the bottom right.
• Click over to the Show Markdown Card to see the results.

Notice that we populated some of the text with actual results from the database. Keep in mind that to print the results of a query in Markdown, the query must begin with an exclamation point (!) and two back-ticks (``) and end with two more back-ticks (``).

• Click back to the Setup Markdown Card.

We will use similar syntax to populate the elements of an interactive form in the next section.

3.2 Interactive Markdown Forms¶

Here is where things get really fun for both you and your users. Let’s actually provide the functionality that we promise with the title of Average Weight by City.

First we want the user to select the state to report on. This will then allow us to query the database for patients that reside in cities within that state.

• Replace the contents of the current Markdown Setup Card with the following code.

### Select the state to report on

state = {!``SELECT DISTINCT(state) FROM `/devguide/devdb/patients` ORDER BY state``}

• Select Run Query in the bottom right.
• Click over to the Show Markdown Card to see the results.
• Click on the dropdown next to State to see that the element was populated with the query we typed in.
• Flip the Show Markdown Card over by clicking the icon in the upper right.
• Select Wrap.

Note that your interface should now look similar to the following:

You can click and drag the left and right hand grips just as before to see the previous cards.

• Click on the deck to make it active.
• Flip the deck by clicking the icon.
• Select Mirror.

Your interface should now look similar to the following:

We have just mirrored a deck. This means that the second deck starts off from where the first left off, but it also means any changes to the first deck will immediately impact the second deck as well. This is how we chain events in a Workspace and allow the actions in one deck to affect other decks.

• Click on the new second deck to make it active.
• Create a new card in this second deck, selecting the Query Card.
• Type in or paste the following query into the Query Card:

SELECT
  city AS City,
  AVG(weight) AS AvgWeight
FROM `/devguide/devdb/patients`
WHERE
  state IN :state
GROUP BY
  city
ORDER BY AVG(weight) DESC

Whenever a variable from a Markdown form is used in a query it must be preceded by a colon ( : ).

Also note that we can ORDER BY an aggregation value such as AVG.

• Select Run Query in the bottom right.
• Click on the right grip to create a new card and select the Preview Table Card.

• Select a different state in the first deck and watch the results table update automatically.

Viewing data in table form is useful but sometimes a graphical representation makes all the difference. To prepare for that, let’s go back and change the query and limit the results to 20 cities, so a bar chart doesn’t appear crowded.

• Click the left grip to go back to the Query Card.
• Add the following line to the end of the query:

LIMIT 20

• Select Run Query in the bottom right.
• Slide back over to the Preview Table Card.

Now we are ready to add some visualizations!

3.3 Creating a Chart¶

Before creating an actual chart we need to set it up. Remember earlier that decks can build off one another. We need to now mirror the Preview Table Card:

• Click on second deck to make it active.
• Click on the flip icon to flip the deck over.
• Select Mirror.
• Resize so that your interface looks similar to the following image:

• Select the new deck and click on the right grip and then select the Setup Chart Card.
• Select the Bar Chart icon.

The bar chart icon will change from gray to blue to show that it is active.

• For the Category, select .City as the axis source.
• Slide to the right to create a new card and select Show Chart.

Your interface should now look like the following image:

• Select a new state in the first deck and watch both of the other decks update dynamically.
• Try hovering your mouse over the individual bars in the chart and you can view the actual value.

Setting up interactive forms and charts is as simple as that! In the next section we’ll go over how to share these charts with others.

4.1 - Publishing¶

SlamData makes it easy to take all the work you’ve done up to this point and publish it so that others can use it as well.

• Click the flip icon on the Draftboard Card. Note that this is the card that contains all of the existing decks. Just as each deck has a back to it, each card does as well, including the Draftboard Card. Be sure not to flip any of the three decks we’ve created - click the icon in the white box border surrounding the other decks.
• Select Publish deck.

A URL will be presented to you that you can share with others. The URL will only be accessible while SlamData is running.

4.2 - Simple Embedding¶

SlamData allows content authors and developers to embed Decks into external web applications such as customer portals, dashboards, etc.

git clone https://github.com/slamdata/slamdata-dev-examples.git
cd slamdata-dev-examples

<head>
<meta charset="utf-8">
<title>Your Reporting App</title>
<link rel="stylesheet" type="text/css" href="styles.css">
<!-- SLAMDATA SNIPPET 1 -->
<script type="text/javascript">
    var slamdata = window.SlamData = window.SlamData || {};
    slamdata.embed = function(options) {
      var queryParts = [];
      if (options.permissionTokens) queryParts.push("permissionTokens=" + options.permissionTokens.join(","));
      if (options.stylesheets && options.stylesheets.length) queryParts.push("stylesheets=" + options.stylesheets.map(encodeURIComponent).join(","));
      var queryString = "?" + queryParts.join("&");
      var varsParam = options.vars ? "/?vars=" + encodeURIComponent(JSON.stringify(options.vars)) : "";
      var uri = "http://localhost:20223/slamdata/workspace.html" + queryString;
      var iframe = document.createElement("iframe");
      iframe.width = iframe.height = "100%";
      iframe.frameBorder = 0;
      iframe.src = uri + "#" + options.deckPath + options.deckId + "/view" + varsParam;
      var deckElement = document.getElementById("sd-deck-" + options.deckId);
      if (deckElement) deckElement.appendChild(iframe);
    };
</script>
</head>
<body>
<div class="container">
    <nav class="navbar navbar-default" role="navigation">
        <div class="navbar-header">
            <div class="row">
                <a class="navbar-brand" href="index.html"><img width="10" src="images/spacer.png"/></a>
                <a class="navbar-brand" href="index.html"><img src="images/dashboard.svg"/></a>
            </div>
            <div class="row">
                <a class="navbar-brand" href="index.html"><img width="10" src="images/spacer.png"/></a>
                <a class="navbar-brand" href="index.html">Your Reporting App</a>
            </div>
        </div>
    </nav>
    <div id="main">
        <div class="container">
            <div class="row">
                <div class="col-md-6">
                    <H3>Average Weight by City</H3>
                </div>
            </div>
            <!-- SLAMDATA SNIPPET 2 -->
            <div
                style="min-height: 700px;min-width: 800px;"
                class="col-lg-12 col-md-12 col-sm-12"
                class="row"
                id="sd-deck-33a2fbf9-6c1f-487e-b043-f62565572caa">
            </div>
        </div>
    </div>
</div>
<!-- SLAMDATA SNIPPET 3 -->
<script type="text/javascript">
    SlamData.embed({
      deckPath: "/devguide/devdb/Average+Weight+by+City.slam/",
      deckId: "33a2fbf9-6c1f-487e-b043-f62565572caa",
      // An array of custom stylesheets URLs can be provided here
      stylesheets: []
    });
</script>
</body>

5.1 Bootstrapping Security¶

If you have already setup authentication for SlamData you may skip this section.

To enable user security a default administrator group must be created along with a user email. In the next step this user will be provided all permissions within SlamData. This allows the user to perform administration tasks within the user interface as well as make calls via the SlamData API that require elevated privileges.

From the SlamData Advanced Edition directory, type the following to bootstrap the SlamData Advanced Edition environment, replacing the email address with the user you wish to authenticate with.

` java -jar quasar.jar bootstrap --admin-group --admin-users you@example.com `

5.2 Creating an OIDC Provider¶

If you have already setup an OIDC provider you may skip this section.

At least one OpenID Connect (OIDC) Provider must be listed in the configuration file for SlamData Advanced Edition. This OpenID Connector Provider (OP) will be trusted by SlamData for authentication information.

The remainder of this guide will assume that a Google OP will be used and the examples are configured based on this assumption. However, any OpenID Connect Provider can be used.

http://localhost:20223/files/auth_redirect.html

5.3 Logging Into SlamData¶

You should now be able to click on the application tab bar pull out at the top of the page.

You can then click on the Sign in icon to the right.

Once clicked it should display all of the OIDC Providers that are configured, similar to the image below:

Sign in with the user you specified in the bootstrap step above. This user has complete access to all SlamData Advanced Edition functionality.

5.4 New Decks for Secure Embedding¶

In this section we’re going to spend time setting up SlamData so that multiple customers can utilize it from an external web application. This will require creating SQL² Views, new Workspaces and permission tokens.

Additionally we’ll configure SlamData so that reports and views are now stored in a separate directory structure for enhanced security.

SELECT * FROM `/devguide/devdb/patients` WHERE state = "CO"

SELECT
  city AS City,
  AVG(weight) AS AvgWeight
FROM :viewpath
GROUP BY
  city
ORDER BY AVG(weight) DESC
LIMIT 20

cp sample2/report1.html sample2/report2.html

1.1 Counting¶

SELECT COUNT(*)
FROM `/devguide/devdb/patients`

db.patients.aggregate(
  [
    {
      "$group": {
        "0": { "$sum": { "$literal": NumberInt("1") } },
        "_id": { "$literal": null }
      }
    },
    { "$limit": NumberLong("11") }],
  { "allowDiskUse": true });

SELECT COUNT(*)
FROM `/devguide/devdb/patients`
WHERE age >= 50

db.patients.aggregate(
  [
    {
      "$match": {
        "$and": [
          {
            "$or": [
              { "age": { "$type": NumberInt("16") } },
              { "age": { "$type": NumberInt("18") } },
              { "age": { "$type": NumberInt("1") } },
              { "age": { "$type": NumberInt("2") } },
              { "age": { "$type": NumberInt("9") } },
              { "age": { "$type": NumberInt("8") } }]
          },
          { "age": { "$gte": NumberInt("50") } }]
      }
    },
    {
      "$group": {
        "0": { "$sum": { "$literal": NumberInt("1") } },
        "_id": { "$literal": null }
      }
    },
    { "$limit": NumberLong("11") }],
  { "allowDiskUse": true });

1.2 Concatenating Field Values¶

Use the double-pipe (||) symbol to concatenate char and string values.

SQL Example

SELECT
  "Full Name is " ||
  first_name      ||
  ' '             ||
  last_name
FROM `/devguide/devdb/patients`

MongoDB query equivalent

db.patients.aggregate(
  [
    { "$limit": NumberLong("11") },
    {
      "$project": {
        "0": {
          "$cond": [
            {
              "$and": [
                { "$lte": [{ "$literal": "" }, "$last_name"] },
                { "$lt": ["$last_name", { "$literal": {  } }] }]
            },
            {
              "$cond": [
                {
                  "$and": [
                    { "$lte": [{ "$literal": "" }, "$first_name"] },
                    { "$lt": ["$first_name", { "$literal": {  } }] }]
                },
                {
                  "$concat": [
                    {
                      "$concat": [
                        {
                          "$concat": [{ "$literal": "Full Name is " }, "$first_name"]
                        },
                        { "$literal": " " }]
                    },
                    "$last_name"]
                },
                { "$literal": undefined }]
            },
            { "$literal": undefined }]
        }
      }
    }],
  { "allowDiskUse": true });

1.3 Converting Data Types¶

SlamData provides the ability to convert between many data types.

SELECT
  TO_STRING(DATE_PART("year", last_visit))  ||
  "-"                                       ||
  TO_STRING(DATE_PART("month", last_visit)) AS Year_Month
FROM `/devguide/devdb/patients`

db.patients.mapReduce(
  function () {
    emit.apply(
      null,
      (function (key, value) {
        return [
          key,
          {
            "Year_Month": (((value.last_visit instanceof Date) || (value.last_visit instanceof Timestamp)) && ((value.last_visit instanceof Date) || (value.last_visit instanceof Timestamp))) ? ((((value.last_visit.getFullYear() instanceof NumberInt) || (value.last_visit.getFullYear() instanceof NumberLong)) ? String(value.last_visit.getFullYear()).replace(
              RegExp("[^-0-9]+", "g"),
              "") : ((value.last_visit.getFullYear() instanceof Timestamp) || (value.last_visit.getFullYear() instanceof Date)) ? value.last_visit.getFullYear().toISOString() : String(value.last_visit.getFullYear())) + "-") + ((((value.last_visit.getMonth() + 1) instanceof NumberInt) || ((value.last_visit.getMonth() + 1) instanceof NumberLong)) ? String(value.last_visit.getMonth() + 1).replace(
              RegExp("[^-0-9]+", "g"),
              "") : (((value.last_visit.getMonth() + 1) instanceof Timestamp) || ((value.last_visit.getMonth() + 1) instanceof Date)) ? (value.last_visit.getMonth() + 1).toISOString() : String(value.last_visit.getMonth() + 1)) : undefined
          }]
      })(
        this._id,
        this))
  },
  function (key, values) { return values[0] },
  {
    "out": { "replace": "tmp.gen_840a7e9a_0", "db": "devdb" },
    "limit": NumberLong("11")
  });
db.tmp.gen_840a7e9a_0.aggregate(
  [{ "$project": { "Year_Month": "$value.Year_Month" } }],
  { "allowDiskUse": true });

SELECT *
FROM `/devguide/epochtest/c1`
WHERE TO_TIMESTAMP(epoch) <= TIMESTAMP("2016-01-01T00:00:00Z")

db.c1.aggregate(
  [
    {
      "$project": {
        "__tmp2": {
          "$cond": [
            {
              "$and": [
                { "$lt": [{ "$literal": null }, "$epoch"] },
                { "$lt": ["$epoch", { "$literal": "" }] }]
            },
            {
              "$lte": [
                {
                  "$add": [{ "$literal": ISODate("1970-01-01T00:00:00Z") }, "$epoch"]
                },
                { "$literal": ISODate("2016-01-01T00:00:00Z") }]
            },
            { "$literal": undefined }]
        },
        "__tmp3": "$$ROOT"
      }
    },
    { "$match": { "__tmp2": true } },
    { "$limit": NumberLong("11") },
    { "$project": { "value": "$__tmp3", "_id": false } }],
  { "allowDiskUse": true });

1.4 Grouping¶

{
  "_id": ObjectId("...abcd1234..."),
  ...
  "city": "AUSTIN",
  "first_name": "John",
  "last_name": "Smith",
  "middle_name": "Duke",
  "last_visit": ISODate("2016-01-01T15:56:36Z"),
  "weight": 145
  ...
}

SELECT
  COUNT(*) as cnt,
  TO_STRING(DATE_PART("year",last_visit))
  || "-Q" ||
  TO_STRING((DATE_PART("quarter",last_visit)) - (DATE_PART("quarter",last_visit) %1)) AS QUARTER

FROM `/devguide/devdb/patients`
GROUP BY
  TO_STRING(DATE_PART("year",last_visit))
  || "-Q" ||
  TO_STRING((DATE_PART("quarter",last_visit)) - (DATE_PART("quarter",last_visit) %1))
ORDER BY QUARTER ASC

SELECT
  COUNT(*) as cnt,
  TO_STRING(DATE_PART("year",last_visit))
  || "-Q" ||
  TO_STRING((DATE_PART("quarter",last_visit)) - (DATE_PART("quarter",last_visit) %1)) AS QUARTER
FROM `/devguide/devdb/patients`
GROUP BY
  TO_STRING(DATE_PART("year",last_visit))
  || "-Q" ||
  TO_STRING((DATE_PART("quarter",last_visit)) - (DATE_PART("quarter",last_visit) %1))
ORDER BY QUARTER ASC

1.2 Nested Data¶

SlamData provides the flattening operator ([*]) to iterate through arrays and extract values from fields.

SELECT
  last_name || "," || first_name AS NAME,
  age AS PATIENT_AGE,
  codes AS Z_CODES
FROM `/devguide/devdb/patients`

db.patients.aggregate(
  [
    { "$limit": NumberLong("11") },
    {
      "$project": {
        "NAME": {
          "$cond": [
            {
              "$and": [
                { "$lte": [{ "$literal": "" }, "$first_name"] },
                { "$lt": ["$first_name", { "$literal": {  } }] }]
            },
            {
              "$cond": [
                {
                  "$and": [
                    { "$lte": [{ "$literal": "" }, "$last_name"] },
                    { "$lt": ["$last_name", { "$literal": {  } }] }]
                },
                {
                  "$concat": [
                    { "$concat": ["$last_name", { "$literal": "," }] },
                    "$first_name"]
                },
                { "$literal": undefined }]
            },
            { "$literal": undefined }]
        },
        "PATIENT_AGE": "$age",
        "Z_CODES": "$codes"
      }
    }],
  { "allowDiskUse": true });

SELECT
  last_name || "," || first_name AS NAME,
  age AS PATIENT_AGE,
  codes[*] AS Z_CODES
FROM `/devguide/devdb/patients`

db.patients.aggregate(
  [
    {
      "$project": {
        "__tmp8": {
          "$cond": [
            {
              "$and": [
                { "$lte": [{ "$literal": [] }, "$codes"] },
                { "$lt": ["$codes", { "$literal": BinData(0, "") }] }]
            },
            "$codes",
            { "$literal": [undefined] }]
        },
        "__tmp9": "$$ROOT"
      }
    },
    { "$unwind": "$__tmp8" },
    { "$limit": NumberLong("11") },
    {
      "$project": {
        "NAME": {
          "$cond": [
            {
              "$and": [
                { "$lte": [{ "$literal": "" }, "$__tmp9.first_name"] },
                { "$lt": ["$__tmp9.first_name", { "$literal": {  } }] }]
            },
            {
              "$cond": [
                {
                  "$and": [
                    { "$lte": [{ "$literal": "" }, "$__tmp9.last_name"] },
                    { "$lt": ["$__tmp9.last_name", { "$literal": {  } }] }]
                },
                {
                  "$concat": [
                    { "$concat": ["$__tmp9.last_name", { "$literal": "," }] },
                    "$__tmp9.first_name"]
                },
                { "$literal": undefined }]
            },
            { "$literal": undefined }]
        },
        "PATIENT_AGE": "$__tmp9.age",
        "Z_CODES": "$__tmp8"
      }
    },
    {
      "$project": { "NAME": true, "PATIENT_AGE": true, "Z_CODES": true, "_id": false }
    }],
  { "allowDiskUse": true });

1.1 Data Types¶

The following data types are used by SQL².

1.2 Clauses, Operators, and Functions¶

The following clauses are supported:

The following operators are supported:

The following functions are supported:

2.1 Select all values from a path¶

To select all values from a path, use the asterisk (*).

Example:

SELECT *
FROM `/users`

2.2 Select specific fields from a path¶

To select specific fields from a path, use the field names, separated by commas.

Example:

SELECT name, age
FROM `/users`

2.3 Path Aliases¶

Follow the path name with an AS and an alias name, and then you can use the alias name when specifying the fields. This is especially useful when you have data from more than one source.

Example:

SELECT c.name, c.age
FROM `/users` AS c

3.1 Filtering using a numeric value¶

Example:

SELECT c.name
FROM `/users` AS c
WHERE c.age > 40

3.2 Filtering using a string value¶

Example:

SELECT c.name
FROM `/users` AS c
WHERE c.name = "Sherlock Holmes"

3.3 Filtering using multiple Boolean predicates¶

Example:

SELECT
  c.name FROM `/users` AS c
WHERE
  c.name = "Sherlock Holmes" AND
  c.street = "Baker Street"

4.1 - Examples¶

Using mathematical operations:

SELECT c.age + 2 * 1 / 4 % 2
FROM `/users` AS c

Concatenating strings:

SELECT c.firstName || ' ' || c.lastName AS name
FROM `/users` AS c

Filtering by fuzzy string comparison using the LIKE operator:

SELECT * FROM `/users` AS c
WHERE c.firstName LIKE "%Joan%"

Filtering by regular expression:

SELECT * FROM `/users` AS c
WHERE c.firstName ~ "[sS]h+""

5.1 Filter based on a timestamp¶

Use the TIMESTAMP operator to convert a string into a date and time. The string should have the format YYYY-MM-DDTHH:MM:SSZ.

Example:

SELECT *
FROM `/log/events` AS c
WHERE c.ts > TIMESTAMP("2015-04-29T15:16:55Z")

5.2 Filter based on a time¶

Use the TIME operator to convert a string into a time. The string should have the format HH:MM:SS.

Example:

SELECT *
FROM `/log/events` AS c
WHERE c.ts > TIME("15:16:55")

5.3 Filter based on a date¶

Use the DATE operator to convert a string into a date. The string should have the format YYYY-MM-DD.

Example:

SELECT *
FROM `/log/events` AS c
WHERE c.ts > DATE("2015-04-29")

5.4 Filter based on part of a date¶

Use the DATE_PART function to select part of a date. DATE_PART has two arguments: a string that indicates what part of the date or time that you want and a timestamp field. Valid values for the first argument are century, day, decade, dow (day of week), doy (day of year), hour, isodoy, microseconds, millenium, milliseconds, minute, month, quarter, second, and year.

Example:

SELECT DATE_PART("day", c.ts)
FROM `/log/events` AS c

5.5 Filter based on a Unix epoch¶

Use the TO_TIMESTAMP function to convert Unix epoch (milliseconds) to a timestamp.

Example:

SELECT *
FROM `/log/events` AS c
WHERE c.ts > TO_TIMESTAMP(1446335999)

6.1 Group based on a single field¶

Use GROUP BY to group results by a field.

Example:

SELECT
    c.age,
    COUNT(*) AS cnt
FROM `/users` AS c
GROUP BY c.age

6.2 Group based on multiple fields¶

You can group by multiple fields with a comma-separated list of fields after GROUP BY.

Example:

SELECT
    c.age,
    c.gender,
    COUNT(*) AS cnt
FROM `/users` AS c
GROUP BY c.age, c.gender

6.3 Group based on date part¶

Use the DATE_PART function to group by a part of a date, such as the month.

Example:

SELECT
    DATE_PART("day", c.ts) AS day,
    COUNT(*) AS cnt
FROM `/log/events` AS c
GROUP BY DATE_PART("day", c.ts)

6.4 Filter within a group¶

Filter results within a group by adding a HAVING clause followed by a Boolean predicate.

Example:

SELECT
    DATE_PART("day", c.ts) AS day,
    COUNT(*) AS cnt
FROM `/prod/purger/events` AS c
GROUP BY DATE_PART("day", c.ts)
HAVING c.gender = "female"

6.5 Filter with Arbitrary Value¶

ARBITRARY returns an arbitrary value from a set. Each target data source may implement this differently but is intended to retrieve a single value from a set in the cheapest way, and is not necessarily deterministic.

6.6 Double grouping¶

Perform double-grouping operations by putting operators inside other operators. The inside operator will be performed on each group created by the GROUP BY clause, and the outside operator will be performed on the results of the inside operator.

Example:

This query returns the average population of states. The outer aggregation function (AVG) operates on the results of the inner aggregation (SUM) and GROUP BY clause.

SELECT AVG(SUM(pop))
FROM `/population`
GROUP BY state

7.1 Nesting¶

Nesting is represented by levels separated by a full stop (.).

Example:

SELECT c.profile.address.street.number
FROM `/users` AS c

7.2 Arrays¶

Array elements are represented by the array index in square brackets ([n]).

Example:

SELECT c.profile.allAddress[0].street.number
FROM `/users` AS c

SELECT c.profile.allAddresses[*]
FROM `/users` AS c

SELECT c.profile.{*}
FROM `/users` AS c

SELECT DISTINCT *
FROM `/users` AS c
WHERE c.profile.allAddresses[*].street.number = "221B"

8.1 Pagination¶

Pagination is used to break large return results into smaller chunks. Use the LIMIT operator to set the number of results to be returned and the OFFSET operator to set the index at which the results should start.

Example (Limit results to 20 entries):

SELECT *
FROM `/users`
LIMIT 20

Example (Return the 100th to 119th entry):

SELECT *
FROM `/users`
OFFSET 100
LIMIT 20

8.2 Sorting¶

Use the ORDER BY clause to sort the results. You can specify one or more fields for sorting, and you can use operators in the ORDER BY arguments. Use ASC for ascending sorting and DESC for descending sorting.

Example (Sort users by ascending age):

SELECT *
FROM `/users`
ORDER BY age ASC

Example (Sort users by last digit in age, descending, and full name, ascending):

SELECT *
FROM `/users`
ORDER BY age % 10 DESC, firstName + lastName ASC

9.1 Examples¶

This example returns the names of employees and the names of the departments they belong to by matching up the employee department ID with the department’s ID, where both IDs are ObjectID types.

SELECT
    emp.name,
    dept.name
FROM `/employees` AS emp
JOIN `/departments` AS dept ON dept._id = emp.departmentId

If one of the IDs is a string, then use the OID operator to convert it to an ID.

SELECT
    emp.name,
    dept.name
FROM `/employees` AS emp
JOIN `/departments` AS dept ON dept._id = OID(emp.departmentId)

9.2 Join Considerations¶

On JOINs with more than two collections or tables, the standard rule of thumb is to place the tables in order from smallest to largest. If the collections a, b, and c have 4, 8, and 16 documents respectively, then ordering FROM `/a`, `/b`, `/c` is most efficient with WHERE a._id = b._id.

If, however, the filter condition is WHERE b._id = c._id then the appropriate ordering would be FROM `/b`, `/c`, `/a` WHERE b._id = c._id. This is because without the filter |a ⨯ b| = 32 which is less than |b ⨯ c| = 128, but with the filter, |b ⨯ c| is limited to the number of documents in b, which is 8 (and which is lower than the unconstrained |a ⨯ b|).

10.1 Conditionals¶

Use the CASE expression to provide if-then-else logic to SQL². The CASE sytax is:

SELECT (CASE <field>
    WHEN <value1> THEN <result1>
    WHEN <value2> THEN <result2>
    ...
    ELSE <elseResult>
    END)
FROM `<path>`

Example:

The following example generates a code based on gender string values.

SELECT (CASE c.gender
    WHEN "male" THEN 1
    WHEN "female" THEN 2
    ELSE 3
    END) AS genderCode
FROM `/users` AS c

10.2 Nulls¶

Use the COALESCE function to evaluate the arguments in order and return the current value of the first expression that initially does not evaluate to NULL.

Example:

This example returns a full name, if not null, but returns the first name if the full name is null.

SELECT COALESCE(c.fullName, c.firstName) AS name
FROM `/users` AS c

11.1 Converting to Boolean¶

SQL² allows String data type fields with values of either "true" or "false" to be converted to their corresponding Boolean value.

Prefix the field name with the BOOLEAN function.

Example:

SELECT BOOLEAN(survey_complete) AS Survey
FROM `/users`

11.2 Converting to Strings¶

SQL² allows most fields to be converted to String data types by prefixing the field name with the TO_STRING function.

Example:

SELECT TO_STRING(zip_code) AS ZipCode
FROM `/users`

11.3 Converting to Integer¶

SQL² allows string representations of valid integer values to be converted to an actual integer number. Prefix the field name with the INTEGER function.

If a field named myField had the value of "1234" as a String, it could be converted to an integer with this example:

SELECT INTEGER(myField) AS MyField
FROM `/users`

If a field is not a valid string representation of an integer value then a null value will be returned.

11.4 Converting to Decimal¶

SQL² allows string representations of valid integer and decimal values to be converted to an actual decimal number. Prefix the field name with the DECIMAL function.

If a field named myField had the value of "1.234" as a String, it could be converted to a decimal with this example:

SELECT DECIMAL(myField) AS MyField
FROM `/users`

If the field does not a contain a valid string representation of a numeric value, such as "123" or "123.456" then a null value will be returned.

11.5 Converting to Dates and Times¶

SQL² allows strings in a specific format to be converted to date and time related data types. See Section 5 for examples of converting to date, time, and timestamp types.

12.1 Single Values¶

Single values are generated in Markdown through the following elements:

• String text field
• Numeric text field
• Calendar Picker
• Calendar / Time Picker
• Radio Boxes
• Drop Downs

For more information on Markdown / Slamdown and how to generate form elements see the Form Elements Section of the Slamdown Reference Guide.

Variables can be used in queries by prefixing the variable name with a colon (:).

For example, if the following Markdown code was used:

### Select year to report on

year = {2011,2012,2013,2014,2015,2016}

The value selected by the user from the year dropdown can be referenced like this:

SELECT * FROM `/users`
WHERE last_visit = :year

12.2 Multiple Values¶

Multiple values are generated in Markdown only through the Check Boxes UI element.

For example, if the following Markdown code was used:

### Select years to report on

years = [x] 2014 [] 2015 [] 2016 [] 2017

The values selected by the user from the years set of Check Boxes should be referenced using the IN clause:

SELECT * FROM `/users`
WHERE last_visit IN :years

This example would find all users who have a last_visit that matched one of the check boxes selected.

13.1 MongoDB¶

SELECT _id AS cust_id
FROM `/users`

SELECT *
FROM `/foo`
WHERE _id = OID("abc123")

2.1 Horizontal Rules¶

Three dashes or more create a horizontal line. Put a blank line above and below the dashes.

Example:

Text here

---

More text here

This results in the following output:

Text here

More text here

2.2 Headers¶

Use hash marks (#) for ATX headers, with one hash mark for each level.

Example:

# Top level
## Second level
### Third level

This results in a first, second, and third level heading, as follows:

2.3 Code Blocks¶

You can create blocks of code (that is, literal content in monospace font) in two ways:

1. Indented code blocks

Indent by four spaces.

Example:

    for (int i = 0; i < 10; i++)
        sum += myArray[i];

2. Fenced code blocks

Start and end with three or more backtick (`) characters.

Example:

```
for (int i = 0; i < 10; i++)
    sum += myArray[i];
```

Both Indented Code Blocks and Fenced Code Blocks result in the following output:

for (int i = 0; i < 10; i++)
    sum += myArray[i];

2.4 Paragraphs¶

Paragraphs are separated by a blank line.

Example:

This is paragraph 1.

This is paragraph 2.

This results in the following output:

This is paragraph 1.

This is paragraph 2.

2.5 Block quotes¶

Start with a greater than sign (>) to create a block quote.

Example:

> This is a block quote.

This results in the following output:

This is a block quote.

2.6 Lists¶

Ordrered lists start with numbers followed by a full stop (.). The actual numbers in the SlamDown do not matter, as the list will be displayed with ascending indices.

Example:

1. First item
2. Second item
3. Third item

This results in the following output:

1. First item
2. Second item
3. Third item

Unordered lists start with either an asterisk (*), dash (-), or a plus sign (+). All three are interchangeable.

Example:

- First item
- Second item
- Third item

This results in the following output:

• First item
• Second item
• Third item

3.1 Emphasis and Strong Emphasis¶

Surround content with asterisks (*) for emphasis and surround it with double asterisks (**) for strong emphasis.

Example:

This is *important*. This is **more important**.

This results in the following output:

This is important. This is more important.

3.2 Links¶

Links contain the link title in square brackets ([]) and the link destination in parentheses (()).

Example:

[SlamData](http://slamdata.com)

This results in the following output:

SlamData

If the link title and destination are the same, an autolink can be used, where the URI is contained in angled brackets (<>).

Example:

<http://slamdata.com>

This results in the following output:

http://slamdata.com

3.3 Images¶

Images start with an explanation mark (!), followed by the image description in square brackets ([]) and the image URI in parentheses (()).

Example:

![SlamData Logo](https://media.licdn.com/media/p/6/005/088/002/039b9f8.png)

This results in the following output:

3.4 Inline code formatting¶

To add code formatting (literal content with monospace font) inline, put the content between backtick (`) characters.

Example:

Start SQL statements with `SELECT * FROM`

This results in the following output:

Start SQL statements with SELECT * FROM

5.1 Text Field¶

Use one or more underscores (_) to create a text input field where a user can add text.

The following code creates an input file for a user’s interests. The value can then be referred to as :interests.

Example:

interests = ________

Optionally, the input field can be pre-filled with a default value by having it after the underscores in parentheses. The following code creates an input field called interests with a default value of “SlamData”. The value can then be referred to as :interests.

Example:

interests = ________ (SlamData)

5.2 Numeric Field¶

By default, input fields are evaluated as string types. To enforce a numeric type, prefix the underscores with the (#) symbol. A default value can also be provided.

Example:

year = #________  (1999)

5.3 Radio Buttons¶

A set of radio buttons has only one button selected at a time. Radio buttons can be populated with static content or populated by a query.

commute = () car (x) bus () bike

mycolor =
(!``SELECT DISTINCT(color) FROM `/devguide/devdb/colors` ORDER BY color ASC LIMIT 1``)
!``SELECT DISTINCT(color) FROM `/devguide/devdb/colors` ORDER BY color ASC``

5.4 Checkboxes¶

Use brackets ([]) followed by text to indicate checkboxes. In a set of checkboxes each checkbox operates independently.

A checkbox array variable can be used in a query whether it was defined statically in SlamDown or dynamically through an evaluated SQL² query. An example query within a Query Card would look as follows.

Example:

SELECT *
FROM `/mydb/mytable`
WHERE phone IN :phones

phones = [x] iPhone [] Blackberry [x] Android

myphone =
[!``SELECT DISTINCT(phone) FROM `/mydb/mytable` ORDER BY phone ASC LIMIT 1``]
!``SELECT DISTINCT(phone) FROM `/mydb/mytable` ORDER BY phone ASC``

5.5 Dropdowns¶

Dropdowns allow user’s to select one (and only one) value from a list of options, similar to radio buttons. Unlike radio buttons, however, dropdown elements typically take up less space in the browser and are more suitable for longer lists of values.

Use a comma-separated list in braces ({}) to indicate a dropdown element.

A dropdown array variable can be used in a query whether it was defined statically in SlamDown or dynamically through an evaluated SQL² query. An example query within a Query Card would look as follows.

Example:

SELECT *
FROM `/mydb/mytable`
WHERE city IN :mycity

city = {BOS, SFO, NYC}

city = {BOS, SFO, NYC} (NYC)

mycity = {!``SELECT DISTINCT(city) FROM `/mydb/mytable` ORDER BY city ASC``}

5.6 Dates and Times¶

Provide a date, time or both date and time selector by implementing the following syntax.

start = ____-__-__ (2016-04-19)

start = __:__ (02:30 PM)

start = ____-__-__ __:__ (2016-04-19 14:00)

1.1 Configuration File Locations¶

Upon initial launch, SlamData will not have a configuration file. However, once a valid database mount has been configured, a file will be created and used to store mount points. Unless specified on the command line, SlamData will look for its configuration file in the following locations by default:

1.2 Log File Locations¶

SlamData has a single log file whose location depends upon the Operating System. Replace version in the table below with the actual version number that you are running.

2.1 SlamData Won’t Start¶

Follow the steps below to ensure all known issues have been addressed.

1. If an older version of SlamData is installed in a Virtual Machine (VM), it may require more than one CPU core before it will launch. If you are experiencing problems running an older version of SlamData in a VM, try increasing the number of cores and restarting.
2. In older versions of SlamData, an invalid database mount may prevent SlamData from starting. An invalid database mount could be a database that was previously available but is no longer available, credentials may have changed, port number changed, or any other configuration change that does not allow previously validated configurations to successfully connect.

2.2 Accessing SlamData¶

The default SlamData URL is http://<servername>:20223

Example: http://localhost:20223

2.3 How do I see which version I’m running?¶

SlamData’s version will be displayed in the browser title bar or tab title.

The version of the Quasar analytics backend engine can be obtained by browsing to http://<servername>:20223/server/info

Example: http://localhost:20223/server/info

2.4 Running SlamData in the Cloud¶

When running SlamData with a hosting provider, such as Amazon EC2, the most common error encountered is a security policy misconfiguration. SlamData will need to connect to a data source over the same port as a standard database client.

A data source or database server and the SlamData server do not need to run on the same system.

Use the following checklist to ensure network problems are minimized.

1. Verify the security policy for the data source or database server is:

• Accepting incoming connections from the SlamData server IP address.
• Accepting incoming connections on the correct port.

2. If you are still unable to connect to your hosted data source or database system:

• Verify that you can connect with a standard database client from any system.
• Connect with a standard database client from the same system SlamData is running on.