# 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](https://app.tilores.io).
!!!

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](https://www.terraform.io)
and `git` in any version is installed.

Verify your `terraform` and `git` installation by running

```
terraform version
git version
```

!!!warning
Tilores CLI does not support Windows. Windows users may consider installing a
[linux subsystem](https://docs.microsoft.com/en-us/windows/wsl/install).
!!!

## 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:

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

## Submit and Search First Record

!!!
Please refer to the [authentication documentation](authentication.md) 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.

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

And afterwards query that record and its entity again.

```graphql
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).

```graphql
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](rules/index.md) for details on how to match or search
using the new field.

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

Submit the modified record.

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

And query the field too.

```graphql
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](schema.md) and
[configure your matching rules](rules/index.md).

Or you may want to [customize the deployment](deployment.md) and understand how
the [API is secured](authentication.md).