API Example - Upload Data to a Boat

This example shows how to upload one or more log files to a boat, to achieve the same result as the Upload Data feature in the web app user interface.

Step 1 - Identify the Boat to Upload Data to

Find the key (unique identifier) of the boat you want to upload data to. That key will look like Boat_xxx-xxx-xxx-xxx. You can can easily get it from the Njord Analytics web URL when navigating to the boat (e.g. on https://app.sailnjord.com/data/Boat_xxx-xxx-xxx-xxx), or you can list boats in a GraphQL API request and request their name and key. To list all boats whose name contains "Test", perform this query:

{
  listBoats(filter: { nameMatches: "Test" }) {
    boat {
      key
      name
    }
  }
}

You will use the boat's key in the following requests.

Step 2 - Upload Data

Any data files you want to load need to be uploaded to an AWS S3 bucket, as direct file uploads to the GraphQL API are not supported. You can use your own S3 bucket if you like (must be world readable), or use an Njord-owned bucket. The latter option is recommended and is described here.

Perform the following query (insert the chosen boat key) to get bucket details and AWS credentials to access it. Note the prefix, all files you upload must be stored under this prefix as only PutObject requests under this prefix are permitted with the provided credentials.

{
  getS3UploadDestination(type: Data, boat: "Boat_...") {
    awsRegion
    endpoint
    bucketName
    prefix
    accessKeyId
    secretAccessKey
    sessionToken
    expiration
  }
}

Upload all files to the S3 bucket using an AWS client of your choice and note each file's full Key.

Step 3 - Generate Processing Instructions and Start File Processing

In the most basic form, when you want to upload only one file without any custom options, the request would look like this (insert the chosen boat key and uploaded file key):

mutation {
  createUploadV2(
    input: {
      boatKey: "Boat_..."
      processInput: {
        source: {
          files: [
            {
              s3Bucket: "user-uploads.prod.sailnjord.com"
              s3Key: "<prefix>/yourfile.csv"
            }
          ]
        }
        steps: [{ addDerivedColumns: { add: true } }]
      }
    }
  ) {
    key
    state
  }
}

Note the key of the upload object, which allows you to confirm the progress and result of your upload in the next step.

Many options exist to manipulate uploaded files and combine them in different ways, which can be specificed through processing instructions (input field processInput). To understand these options, is best to perform the equivalent upload using the Njord Analytics web app, and inspect the processInput in the request sent to the API.

Step 4 - Verify Upload Success or Failure

To check the status of your upload, perform the following request and repeat until state becomes Completed or Failed. This step is optional and is for your information only, processing will normally complete in a few seconds up to a minute without further action. Uploaded data will show up under the selected boat in the Njord Analytics web app.

{
  upload(key: "Upload_...") {
    key
    state
    boat {
      name
    }
    files {
      originalFileName
    }
    processedSegments {
      key
      startTime
      endTime
    }
    errorMessage
    logMessages
  }
}

To more easily inspect the result of your upload, you may also visit the following URL (insert your boat and upload keys): https://app.sailnjord.com/data/Boat_.../upload/Upload_...