FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

v10 migration FAQ

See also: Migrate to FQL v10

This guide provides answers to frequently asked questions (FAQs) related to FQL v4-to-v10 migrations.

Do I need to migrate my data to use v10?

No. FQL v10 is backward-compatible with your existing v4 data. v10 can query and access documents added using v4 (and vice versa). You can incrementally transition v4 queries to v10 in your application.

v10 uses projection to change how documents are presented. However, it doesn’t change the underlying structure of stored documents.

See Document structure improvements

Can I mix v4 and v10 queries?

Yes. To use an FQL v10 query in v4:

  1. Encapsulate the v10 query in a v4 user-defined function (UDF).

  2. Call the UDF in your v4 queries.

Use the same approach to run v4 queries in v10.

These workarounds are provided as a temporary convenience for migration. They aren’t intended for long-term use. You must migrate your UDFs to v10 before the v4 end of life (EOL).

See User-defined functions

What v4 resource definitions do I need to rewrite for v10?

You must migrate definitions for the following resource types to v10 before the v4 EOL:

  • Access providers

  • Indexes

  • User-defined roles

  • UDFs

Other resource definitions are automatically migrated to v10. In v10, you typically define resources using Fauna Schema Language (FSL) schema.

See Get started with schema management

Access providers

To convert a v4 access provider definition to v10, open the definition as FSL in the Fauna Dashboard and save the result.

Indexes and UDFs

You can incrementally migrate v4 index and UDF definitions to v10. FQL v10 can call v4 UDFs. Similarly, v4 can call v10 UDFs.

You can’t directly use v4 indexes in v10. Instead, use the v4 index in a v4 UDF. Then call the v4 UDF in FQL v10. Use the same approach to use v10 indexes in v4.

See User-defined functions, Indexes

User-defined roles

You can authorize v10 transactions using v4 roles. This lets you incrementally migrate v4 role definitions to v10.

You can’t use FQL v4 methods to create v10 role definitions. The structure of role definitions has changed significantly from v4 to v10. See Access provider and role definitions.

What happens if I don’t migrate by the v4 EOL?

We are communicating this EOL 13 months in advance to provide adequate time for you to complete your migration by June 30, 2025. If you are unable to meet this deadline, contact support@fauna.com so we can help you with your plans.

What if my collection or UDF uses a reserved name?

FQL v10 has several reserved words, such as the Collection and Role collection names.

If you have an existing collection or UDF with a reserved name, you won’t be able to access the resource using that name. Instead, assign it an alias. Use this alias to access the resource in FQL v10 queries.

For example, you can add a Product alias to a collection named Collection:

// Adds the `Product` alias to
// an existing collection named `Collection`.
Collection.byName("Collection").update(
  {
    alias: "Products"
  }
)

// Uses the `Product` alias to access
// the collection in v10 queries.
Products.firstWhere(.name == "Hard Anodised 12 Kadhai")
Products.create(...)
See Reserved collection names

Has document metadata changed?

Yes. While the underlying structure of documents has not changed, all v10 documents now include the following top-level metadata fields in v10:

  • coll: The name of the document’s collection

  • id: A string-encoded 64-bit integer identifier that’s unique to the document in the collection

  • ts: A timestamp of the latest write to the document

v10 documents can also include an optional ttl timestamp. A document is permanently deleted on its ttl.

See Metadata fields

How do I avoid conflicts with reserved fields in v10?

Use the following v10 methods to create and modify documents that may contain reserved field names:

Rather than returning an error or overwriting reserved fields, these methods safely nest values for fields with reserved names in the data field.

See Avoid conflicts with reserved fields

What drivers does FQL v10 support?

JavaScript, Python, and Go drivers are currently supported in FQL v10.

Java and C# driver availability is planned for summer 2024.

How do I know what version of FQL I’m using?

The fauna-shell CLI and Fauna Dashboard default to FQL v10. Your application may be using FQL v4 if any process or part of your application uses an early version of the Fauna drivers or the fauna-shell CLI. Audit your application for processes that uses:

What will happen to the v4 Dashboard?

Customers who are still using FQL v4 will continue to have the ability to manage v4 resources from the v4 Dashboard.

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!