Create

Create( collection, param_object )
Create( collection, param_object )
Create( collection, param_object )
Create( collection, param_object )
create( collection, param_object )
Create( collection, param_object )

Description

The Create function adds a new document to a collection. The collection_ref parameter indicates in what collection the document should be created, while param_object contains the document data and optional metadata.

Parameters

Argument Type Definition and Requirements

collection

String or Reference

The name, or reference, of the collection that should contain the new document. A collection reference can be acquired using the Collection function.

param_object

Object

The param_object fields are described below.

param_object

Field Name Field Type Definition and Requirements

data

Object

The user’s single, changeable document.

credentials

Object

Optional - The permissions for this document.

delegates

Object

Optional - A group or delegates to check security. See delegates in the Security reference.

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 actually occurs.

As of version 3.0.0, the ttl field is honored on read — a document that should have been removed behaves as if it has been removed. However, until removal actually occurs due to background task processing, you can continue to access the history of the document, provided you have its reference, via the Events function.

Returns

A document containing both the data and metadata about the results of the operations.

Field Name Field Type Definition and Requirements

ref

Reference

The reference is an automatically generated identifier within the database uniquely identifying the document created.

data

Object

The data that was inserted with the document.

ts

Integer

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

Examples

The following query creates a document by providing a reference to the collection "spells" and a param_object with a data field. The data field contains the user data to be inserted for this document.

client.Query(
  Create(
    Collection("spells"),
    Obj(
      "data", Obj(
        "name", "Mountainous Thunder",
        "element", "air",
        "cost", 15
      )
    )));
{
  "ref": { "@ref": "classes/spells/181388642581742080" },
  "class": { "@ref": "classes/spells" },
  "ts": 1509244539709690,
  "data": {
    "name": "Mountainous Thunder",
    "element": "air",
    "cost": 15
  }
}
curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "create": { "collection": "spells" },
          "params": {
            "object": {
              "data": {
                "object": {
                  "name": "Mountainous Thunder",
                  "element": "air",
                  "cost": 15
                }
              }
            }
          }
        }'
HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "classes/spells/181388642581742080" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539709690,
    "data": {
      "name": "Mountainous Thunder",
      "element": "air",
      "cost": 15
    }
  }
}
result, _ := client.Query(
    f.Create(
        f.Collection("spells"),
        f.Obj{
            "data": f.Obj{
                "name": "Mountainous Thunder",
                "element": "air",
                "cost": 15,
            },
        },
    ),
)

fmt.Println(result)
map[ref:{181388642581742080 0xc420215ee0 <nil>} ts:1509244539709690 data:map[cost:15 element:air name:Mountainous Thunder]]
System.out.println(
   client.query(
      Create(
            Collection(Value("spells")),
            Obj(
               "data", Obj(
                          "name", Value("Mountainous Thunder"),
                          "element", Value("air"),
                          "cost", Value(15)
                       )
            ))
   ).get());
{
  ref: ref(id = "181388642581742080", collection = ref(id = "spells", collection = ref(id = "collections"))),
  ts: 1526674566636715,
  data: {
    name: "Mountainous Thunder",
    element: "air",
    cost: 15
  }
}
client.query(
  q.Create(
    q.Collection('spells'),
    {
      data: {
        name: 'Mountainous Thunder',
        element: 'air',
        cost: 15,
      },
    },
  )
)
.then((ret) => console.log(ret))
{ ref:
  Ref(id=181388642581742080, collection=Ref(id=spells, collection=Ref(id=collections))),
  ts: 1527274715273882,
  data: { name: 'Mountainous Thunder', element: 'air', cost: 15 } }
client.query(
  q.create(
    q.collection("spells"),
    {
      "data": {"name": "Mountainous Thunder", "element": "air", "cost": 15}
    }
  ))
{
  "ref": { "@ref": "classes/spells/181388642581742080" },
  "class": { "@ref": "classes/spells" },
  "ts": 1509244539709690,
  "data": {
    "name": "Mountainous Thunder",
    "element": "air",
    "cost": 15
  }
}
client.query(
  Create(
    Collection("spells"),
    Obj(
      "data" -> Obj(
        "name" -> "Mountainous Thunder",
        "element" -> "air",
        "cost" -> 15
      )
    )))
{
  "ref": { "@ref": "classes/spells/181388642581742080" },
  "class": { "@ref": "classes/spells" },
  "ts": 1509244539709690,
  "data": {
    "name": "Mountainous Thunder",
    "element": "air",
    "cost": 15
  }
}

The following query creates a document in the posts collection with a specified id (via the Ref function):

Value result = await serverClient.Query(
  Create(
    Ref(Collection("posts"), 1),
    Obj("data", Obj("title", "The first post"))
  )
);
ObjectV(ref: RefV(id = "1", collection = RefV(id = "posts", collection = RefV(id = "collections"))),ts: LongV(1587596508180000),data: ObjectV(title: StringV(The first post)))
result, err := serverClient.Query(
  f.Create(
    f.RefCollection(f.Collection("posts"), 1),
    f.Obj{"data": f.Obj{"title": "The first post"}}))

if (err != nil) {
  fmt.Println(err)
} else {
  fmt.Println(result)
}
{"object":{"data":{"object":{"title":"The first post"}},"ref":{"@ref":{"collection":{"@ref":{"collection":{"@ref":{"id":"collections"}},"id":"posts"}},"id":"1"}},"ts":1587596382540000}}
System.out.println(
    serverClient.query(
        Create(
            Ref(Collection(Value("posts")), Value(1)),
            Obj(
                "data", Obj(
                    "title", Value("The first post")
                )
            )
        )
    ).get());
{ref: ref(id = "1", collection = ref(id = "posts", collection = ref(id = "collections"))), ts: 1587595695090000, data: {title: "The first post"}}
serverClient.query(
  q.Create(
    q.Ref(q.Collection('posts'), '1'),
    { data: { title: 'The first post' } },
  )
)
.then((ret) => console.log(ret))
{
  ref: Ref(Collection("posts"), "1"),
  ts: 1587595447990000,
  data: { title: 'The first post' }
}
print(serverClient.query(
  q.create(
    q.ref(q.collection("posts"), 1),
    {"data": {"title": "The first post"}}
  )
))
{'ref': Ref(id=1, collection=Ref(id=posts, collection=Ref(id=collections))), 'ts': 1587596259820000, 'data': {'title': 'The first post'}}
println(Await.result(
  serverClient.query(
    Create(
      Ref(Collection("posts"), 1),
      Obj("data" -> Obj("title" -> "The first post"))
    )
  ),
  5.seconds
))
{ref: ref(id = "1", collection = ref(id = "posts", collection = ref(id = "collections"))), ts: 1587595971600000, data: {title: "The first post"}}

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!