Dashboard quick start

Fauna has two main APIs: GraphQL and FQL (Fauna Query Language). This quick start uses the Fauna Dashboard, and the GraphQL quick start uses the GraphQL Playground.

  1. Sign up for a free account

    When you first log in, you are greeted with an onboarding tutorial. Click the X button to close it. You can return to the tutorial at any time by clicking the question mark ? button at the bottom right.

    The Fauna Dashboard home screen with tutorial prompt

  2. Create a database

    1. Click CREATE DATABASE.

      The Fauna Dashboard new database screen

    2. Enter my_db into the "Name" field.

    3. Select CLASSIC from the Region Groups dropdown menu.

    4. Check the "Use demo data" checkbox.

    5. Click CREATE.

    You have created your first Fauna database!

  3. Browse your database

    The Overview page for the my_db database is displayed. The database has been populated with some collections, indexes, and the corresponding GraphQL schema for a grocery delivery app.

    The Fauna Dashboard database overview screen

    1. Collections

      Click COLLECTIONS in the left sidebar to browse your collections. You’ll see the documents for each collection on the right. If you are familiar with SQL, collections are like tables and documents are like rows in a table, except that each document can contain its own, distinct fields.

      The Fauna Dashboard collections screen

    2. Indexes

      Fauna’s query model relies on indexes to support all query patterns which do not involve looking up documents directly by their Reference. An understanding of index creation and usage is crucial for effective Fauna development.

      Click the INDEXES tab in the left sidebar. If you are familiar with SQL, Fauna’s indexes are like SQL views. Most Fauna queries require a companion index to help avoid performing full scans of collections (which could get expensive), but you can have hundreds of indexes without affecting overall performance.

      The Fauna Dashboard indexes screen

    3. Functions

      Click the FUNCTIONS tab in the left sidebar. User-defined functions (UDFs) contain custom business logic that runs on the server, similar to "stored procedures".

      The Fauna Dashboard functions screen

      This UDF might look weird if it’s your first time seeing FQL, the Fauna Query Language, but FQL is actually pretty easy and tons of fun to learn. FQL is also unique in how much power and precision it gives you with respect to predictable cost and performance as you scale.

  4. Try some FQL

    Now that we know some basic concepts, let’s query our data.

    1. Click on SHELL in the left sidebar to open the web shell.

      The Fauna Dashboard shell screen

    2. Copy the following FQL query:

      Get(Ref(Collection("products"),"202"))
    3. Replace the queries in the bottom panel of the shell by selecting them and then and pasting the copied query.

    4. Click RUN QUERY.

      This query simply gets a document identified by its Reference. A document Reference contains a reference to the document’s collection (in this case, "products") and a unique ID for the document in that collection (in this case, "202"). Fauna’s auto-generated Reference IDs are 18-digits long — you can set your own during document creation, as we have done with the pre-populated demo data to ease copy/pasting.

      The upper panel contains the result of the query:

      The Fauna Dashboard shell screen with the query result

    5. Hover your pointer over the i icon to the left of "Time elapsed" to see the query execution metrics. For example, here we can learn that this query resulted in one read operation.

      The Fauna Dashboard shell screen with the query result and query statistics tooltip

      You can reduce read operations by leveraging indexes and using them as views. Expand the following block to learn more.

      Using indexes as views

      Indexes can be configured to provide any number of document fields. Using indexes, you can often avoid using the Get function to retrieve the values that you need, which reduces the number of read operations required.

      While Get is used to a retrieve a single document, Paginate is required when you want to retrieve details about multiple documents.

      Try the following:

      Paginate(Documents(Collection("products")))

      When an index does not have terms and values defined, it only returns References.

      What if you want the whole document? The most flexible option is the combination of the Map and Get functions.

      The following query takes the array of References from the previous query, then uses the Map function to repeatedly apply an anonymous function for each Reference in the result. The anonymous function (or Lambda) assigns each Reference in the array to the variable product_ref, then uses the Get function to retrieve the referenced document.

      Map(
        Paginate(Documents(Collection("products"))),
        Lambda('product_ref', Get(Var('product_ref')))
      )

      Now, hover over the i icon to see that this costs 17 read operations. During development, you might use many Map/Get queries, so the number of read operations can climb quickly. At some point, you might want to leverage an index for cost-efficiency. Let’s leverage an index to do this.

      Create an index defining which fields from the document that you want to return:

      CreateIndex(
        {
          name: 'product_details',
          source: Collection('products'),
          values: [
            { field: ['data', 'name'] },
            { field: ['data', 'description'] },
            { field: ['data', 'price'] }
          ],
        },
      )

      Now, paginate using the index:

      Paginate(Match(Index("product_details")))

      If you hover over the i icon, you can see that using the Index and Match functions together costs only eight read operations!

      Combining Map with Get might be inexpensive during development, but you should leverage indexes as your usage scales.

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!