CreateCollection

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

Description

The CreateCollection function is used to create a collection that groups documents. Once the collection has been created, it is possible to create documents within 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 within 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. By default, collections retain all versions of a document for 30 days. Document history contributes to consumed storage. Indexes retain the history of indexed fields, which can reduce the performance of indexes as the history accumulates.

Setting history_days to null causes a collection to retain each document’s version history forever. When a collection contains 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; no history is retained.

To learn more about document version history, see Temporality.

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 contain 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 is 30 days.

Setting history_days to null retains this collection’s history forever. Setting history_days to 0 retains only the current version of each document in this collection; no history is retained.

ttl

Timestamp

Optional - A timestamp indicating the document’s time-to-live, which is when the document should be removed. When a document is removed, the document’s existence ceases (as if it never existed); temporal queries cannot recover the document.

Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens) "expires" due to the setting in the ttl field, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal occurs.

As of version 3.0.0, the ttl field is honored on read — an expired but not yet removed document behaves as if removal is complete. But, until removal is completed by background task processing, you can continue to access the history of the document, provided you have its reference, using the Events function.

ttl_days

Integer

Optional - The number of days documents are retained for this collection. Documents which have not been updated within the configured TTL duration are removed. Setting ttl_days to null retains documents forever. The default is null.

Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens) "expires" due to the setting in the ttl_days field, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal actually occurs.

For more immediate removal, use the ttl field on documents that should have limited lifespans. See Documents for details.

permissions

Object

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

Returns

An Object containing the fields returned by the CreateCollection function:

Field Name Field Type Definition and Requirements

ref

Reference

A Reference to the collection that was created.

name

String

The name of the collection that was created.

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 any document in this collection; only the current version is retained. null means that history is retained indefinitely.

Examples

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

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))
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]
System.out.println(
    client.query(
        CreateCollection(Obj("name", Value("boons")))
    ).get());
{
  ref: ref(id = "boons", collection = ref(id = "collections")),
  ts: 1526674566802938,
  history_days: 30,
  name: "boons"
}
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'}
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!