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

For more details, review the migration guide. Contact support@fauna.com with any questions.

CreateCollection

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
CreateCollection( param_object )
create_collection( param_object )
CreateCollection( param_object )
CreateCollection( param_object )
CreateCollection( param_object )

Description

The CreateCollection function is used to create a collection that groups documents. Once the collection is created, it is possible to create documents in the collection. You cannot create a collection and insert documents into that collection in the same transaction.

Unique name required

The collection name must be unique in the database. If you try to lookup a collection by name and only create it if it does not exist, the operation might fail if another transaction has created the collection in the meantime.

Temporality

You can control how long each document in a collection retains its version history with the history_days parameter. Document history contributes to consumed storage. Indexes retain the history of indexed fields, which can increase latency as history accumulates.

See Temporality for details.

Setting history_days to null causes a collection to retain version history for each document indefinitely. When a collection has frequently updated documents, that history increases the storage consumed. When frequently updated documents are indexed, indexes retain the history of indexed fields, too, which can make queries involving those indexes less performant over time.

Setting history_days to 0 retains only the current version of each document in a collection and no history is retained.

Parameters

Parameter Type Definition and Requirements

param_object

Object

The param_object fields are described below.

param_object

Field Name Field Type Definition and Requirements

name

String

The name of the collection.

Cannot be events, sets, self, documents, or _. Cannot have the % character.

data

Object

Optional - This is user-defined metadata for the collection. It is provided for the developer to store information at the collection level.

history_days

Integer

Optional - The number of days that document history is retained for in this collection. The default value is zero days

Setting history_days to null retains history for this collection indefinitely. Setting history_days to the default value of 0 disables history retention for the collection and retains only the current version of each document in this collection.

See Temporality for details.

ttl_days

Integer

Optional - The number of days documents are retained for this collection. Once a document is older than ttl_days, it is removed. Setting ttl_days to null retains documents indefinitely. The default is null.

permissions

Object

Optional - Provides the ability to enable permissions at the collection level. See collection permissions for more details.

Returns

An Object with the fields returned by the CreateCollection function:

Field Name Field Type Definition and Requirements

ref

Reference

A Reference to the created collection.

name

String

The name of the created collection.

ts

Long

The timestamp, with microsecond resolution, associated with the creation of the collection.

history_days

Integer

The number of days to retain history. 0 means that no history is retained for documents in this collection, and only the current version is retained. null means that history is retained indefinitely.

Examples

The following query creates a collection called "boons" with defaults:

client.query(
  q.CreateCollection({ name: 'boons' })
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Collection("boons"),
  ts: 1592054207270000,
  history_days: 30,
  name: 'boons'
}
result = client.query(
    q.create_collection({"name": "boons"})
)
print(result)
{'ref': Ref(id=boons, collection=Ref(id=collections)), 'ts': 1592850281880000, 'history_days': 30, 'name': 'boons'}
result, err := client.Query(
	f.CreateCollection(f.Obj{"name": "boons"}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[history_days:30 name:boons ref:{boons 0xc00009a0f0 0xc00009a0f0 <nil>} ts:1603747133670000]
try
{
    Value result = await client.Query(
        CreateCollection(Obj("name", "boons"))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "boons", collection = RefV(id = "collections")),ts: LongV(1603756173470000),history_days: LongV(30),name: StringV(boons))
CreateCollection({ name: 'boons' })
{
  ref: Collection("boons"),
  ts: 1624310355980000,
  history_days: 30,
  name: 'boons'
}
Query metrics:

  •    bytesIn:   49

  •   bytesOut:  142

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:  804

  • writeBytes:  325

  •  queryTime: 46ms

  •    retries:    0

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!