# Getting Started

This is the quickstart guide for a private SaaS instance. For an even easier start you can sign up for the public SaaS.

Let's create a simple Tilores instance with a lightweight schema and run the API locally.

We will briefly cover these topics:

creating a new Tilores application
customize the schema
test the schema
provide resources for the next steps

# Prerequisites

We will use the Tilores CLI to create our first Tilores instance. This requires that go in at least version 1.24 is installed.

For installing go, please refer to the official installation guide: https://golang.org/doc/install

Verify your go installation afterwards by running

go version

For deploying we will need that terraform in at least version 1.2 and git in any version is installed.

Verify your terraform and git installation by running

terraform version
git version

Tilores CLI does not support Windows. Windows users may consider installing a linux subsystem.

# Install Tilores CLI

Afterwards, install and verify the Tilores CLI:

go install github.com/tilotech/tilores-cli@latest
tilores-cli version

For Mac OS make sure $GOPATH is set and the go binary path is added to $PATH. To do so run the following:

export GOPATH=~/go
export PATH=$PATH:$GOPATH/bin

To make this work for new terminal sessions it needs to be added to the dotfile e.g ~/.bashrc or ~/.zshrc etc., depending on which terminal you use.

# Initialize Project

You can now initialize the project. This will create the required files for your custom GraphQL API.

mkdir my-tilores-project
cd my-tilores-project
tilores-cli init

# Deploy Into Your AWS Account

You can deploy Tilores into your own AWS account using:

tilores-cli deploy --region <your-aws-region>

# Submit and Search First Record

Please refer to the authentication documentation on how to access the GraphQL API.

Let's verify that the previous steps worked by submitting a new record using the GraphQL API testing.

mutation {
  submit(input: {
    records: [
      {
        id: "my-id",
        myCustomField: "some-value"
      }
    ]
  }) {
    recordsAdded
  }
}

And afterwards query that record and its entity again.

query {
  search(input: {
    parameters: {
      myCustomField: "some-value"
    }
  }) {
    entities {
      id
      records {
        id
        myCustomField
      }
    }
  }
}

# Customize Schema

The schema for records are defined via its GraphQL schema, which can be found in your Tilores project under schema/record.graphqls.

To add a new field simply add it to the RecordInput (used for adding data) and the Record (used for querying data).

input RecordInput {
  id: ID!
  myCustomField: String!
  newCustomField: String!
}

type Record {
  id: ID!
  myCustomField: String!
  newCustomField: String!
}

# Test The Modified Schema

After redeploying the application, you can use the new field. Note, that this field will not be used for matching. Please refer to the rules configuration for details on how to match or search using the new field.

tilores-cli deploy --region <your-aws-region>

Submit the modified record.

mutation {
  submit(input: {
    records: [
      {
        id: "my-id",
        myCustomField: "some-value"
        newCustomField: "other-value"
      }
    ]
  }) {
    recordsAdded
  }
}

And query the field too.

query {
  search(input: {
    parameters: {
      myCustomField: "some-value"
    }
  }) {
    entities {
      id
      records {
        id
        myCustomField
        newCustomField
      }
    }
  }
}

# Next Steps

Once you have seen this working, you may want to further customize your schema and configure your matching rules.

Or you may want to customize the deployment and understand how the API is secured.