Getting started

This Shell getting started guide shows you how to:

  1. Define a configuration file endpoint.

  2. Display the configuration file.

  3. Start Fauna Shell.

After starting Fauna Shell, experiment with the Shell commands to gain familiarity with the CLI.

Log in and define a configuration endpoint

The Dashboard quick start describes how to set up an account, and how to create a database and get the database secret.

If you don’t have endpoints defined in the $HOME/.fauna-shell configuration file, use the cloud-login command to create a default configuration endpoint in the fauna-shell configuration file.

  1. Create an endpoint, stepping through each of the prompts.

    • These examples use cloud-example as an endpoint name, but you can choose another name.

    • The email and password are your Fauna account credentials.

    • Choose the endpoint created for your region group

    fauna cloud-login
? Endpoint name cloud-example
? Email address (from https://dashboard.fauna.com/) your.name@yourorg.com
? Password *********
? Endpoints created. Which endpoint would you like to set as default? (Use arrow keys)
  Keep 'cloud-us' endpoint as default // use arrow keys to choose endpoint
  cloud-example-global
❯  cloud-example-us
  cloud-example-eu

  ...

Configuration updated.

    This updates the $HOME/.fauna-shell file to include the following endpoints in addition to previously defined endpoints and sets cloud-example-us: as the default endpoint.

    [.fauna-shell]
default=cloud-example-us

... elided ...

[endpoint.cloud-example-global]
secret=fnAFQyPwW4ACRSqZe31zFBBPe6fh81CPA3G_esVj

[endpoint.cloud-example-us]
secret=fnAFQyPwZe31zWpqZ3-ij5Ghso4erhTiU2RXSQaL

[endpoint.cloud-example-eu]
secret=fnAFQyPwZlAAzh_cxhZe31zKUNvgcNJ6Wj0rEwjY

  2. View your defined endpoints using the endpoint list command:

    fauna endpoint list
Available endpoints:
  local
  cloud-eu
  cloud
  cloud-us
  db.fauna.com
  cloud-example-global
* cloud-example-us
  cloud-example-eu

    The cloud-example-us endpoint is the default endpoint.

Display the configuration file

To view the updated configuration file on Linux, macOS, and Unix-like operating systems, enter:

cat $HOME/.fauna-shell

On a Windows operating system, enter:

type %userprofile%\.fauna-shell

Shell session example

The fauna-shell allows you to query your Fauna database using FQL without installing other libraries.

  1. Create a database and invoke the Shell to start working with the Fauna data model.

    fauna create-database my_app

  2. Start the shell for the my_app database:

    fauna shell my_app
Starting shell for database my_app
Connected to reference:http///127.0.0.1:8443
Type Ctrl+D or .exit to exit the shell
my_app>

  3. After the prompt displays, you can start issuing queries against your database:

    my_app> Collection.create({ name: "Post" })
{
  name: "Post",
  coll: Collection,
  ts: Time("2023-08-15T16:06:01.120Z"),
  indexes: {},
  constraints: []
}

    Note that your results might differ from this example.

  4. Create an index for the Post collection.

    my_app> Post.definition.update({ indexes: { byTitle: { terms: [{ field: ".title" }] } } })
{
  name: "Post",
  coll: Collection,
  ts: Time("2023-08-15T16:07:10.800Z"),
  indexes: {
    byTitle: {
      terms: [
        {
          field: ".title"
        }
      ],
      queryable: true,
      status: "complete"
    }
  },
  constraints: []
}

  5. Insert a new Post document:

    my_app> Post.create({ title: "What I had for breakfast .." })
{
  id: "373143369066480128",
  coll: Post,
  ts: Time("2023-08-15T16:14:57.440Z"),
  title: "What I had for breakfast .."
}

  6. You can insert items in bulk by using array iterator functions:

    my_app> ["My cat and other marvels", "Pondering during a commute", "Deep meanings in a latte"].map(title => Post.create({ title: title }))
[
  {
    id: "373143473418666496",
    coll: Post,
    ts: Time("2023-08-15T16:16:36.960Z"),
    title: "My cat and other marvels"
  },
  {
    id: "373143473419715072",
    coll: Post,
    ts: Time("2023-08-15T16:16:36.960Z"),
    title: "Pondering during a commute"
  },
  {
    id: "373143473420763648",
    coll: Post,
    ts: Time("2023-08-15T16:16:36.960Z"),
    title: "Deep meanings in a latte"
  }
]

  7. Now, fetch the post about latte accessing the collection by id:

    my_app> Post.byId("373143473420763648")
{
  id: "373143473420763648",
  coll: Post,
  ts: Time("2023-08-15T16:16:36.960Z"),
  title: "Deep meanings in a latte"
}

  8. Update the post about the cat, adding some tags:

    my_app> Post.byId("373143473420763648")!.update({ tags: ["cute", "pet"] })
{
  id: "373143473420763648",
  coll: Post,
  ts: Time("2023-08-15T16:17:41Z"),
  title: "Deep meanings in a latte",
  tags: [
    "cute",
    "pet"
  ]
}

  9. Change the content of that post:

    my_app> Post.byId("373143473418666496")!.replace({ title: "My dog and other marvels" })
{
  id: "373143473418666496",
  coll: Post,
  ts: Time("2023-08-15T16:18:32.680Z"),
  title: "My dog and other marvels"
}

  10. Delete the post about latte:

    my_app> Post.byId("373143473420763648")!.delete()
Post.byId("373143473420763648") /* not found */

  11. A null document is returned when you try to fetch the deleted document:

    my_app> Post.byId("373143473420763648")
Post.byId("373143473420763648") /* not found */

  12. Finally, exit the shell by pressing Ctrl+D.

Query using a file

You can use the shell to run a list of queries stored in a file as shown in this example.

  1. Create a setup.fql file that has an FQL expression that creates a collection named Post:

    Collection.create({
  name: "Post",
  indexes: {
    byTitle: {
      terms: [{ field: ".title" }]
    }
  }
})

  2. Create a queries.fql file that has an FQL expression that creates a document in the Post collection:

    Post.create({
  title: "What I had for breakfast .."
})

[
  "My cat and other marvels",
  "Pondering during a commute",
  "Deep meanings in a latte",
].map(title => {
  Post.create({
    title: title
  })
})

  3. Submit the queries with the following commands:

    fauna eval my_app --file=./setup.fql
$ fauna eval my_app --file=./queries.fql

    The database name is my_app and the --file option is the path and file name of the saved the queries. If the database name is omitted, the queries are run on the default fauna shell endpoint.

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!