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

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

The param_object fields are described below.

param_object

Field Name Field Type Definition and Requirements

data

The user’s single, changeable document.

credentials

Optional - The permissions for this document.

delegates

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

ttl

Optional - A timestamp indicating the document’s time-to-live, that is when the document should be removed. When a document is removed, the document’s existence ceases; temporal queries cannot recover the document.

Document removal is handled by a background task, so once the ttl "expires", it could be some time (hours or days) before the document removal occurs. There is no guarantee that removal actually occurs.

Returns

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

Field Name Field Type Definition and Requirements

ref

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

data

The data that was inserted with the document.

ts

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.

curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "create": { "collection": "spells" },
          "params": {
            "object": {
              "data": {
                "object": {
                  "name": "Mountainous Thunder",
                  "element": "air",
                  "cost": 15
                }
              }
            }
          }
        }'
client.Query(
  Create(
    Collection("spells"),
    Obj(
      "data", Obj(
        "name", "Mountainous Thunder",
        "element", "air",
        "cost", 15
      )
    )));
System.out.println(
   client.query(
      Create(
            Collection(Value("spells")),
            Obj(
               "data", Obj(
                          "name", Value("Mountainous Thunder"),
                          "element", Value("air"),
                          "cost", Value(15)
                       )
            ))
   ).get());
result, _ := client.Query(
    f.Create(
        f.Collection("spells"),
        f.Obj{
            "data": f.Obj{
                "name": "Mountainous Thunder",
                "element": "air",
                "cost": 15,
            },
        },
    ),
)

fmt.Println(result)
client.query(
  Create(
    Collection("spells"),
    Obj(
      "data" -> Obj(
        "name" -> "Mountainous Thunder",
        "element" -> "air",
        "cost" -> 15
      )
    )))
client.query(
  q.create(
    q.collection("spells"),
    {
      "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))
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
    }
  }
}
{
  "ref": { "@ref": "classes/spells/181388642581742080" },
  "class": { "@ref": "classes/spells" },
  "ts": 1509244539709690,
  "data": {
    "name": "Mountainous Thunder",
    "element": "air",
    "cost": 15
  }
}
{
  ref: ref(id = "181388642581742080", collection = ref(id = "spells", collection = ref(id = "collections"))),
  ts: 1526674566636715,
  data: {
    name: "Mountainous Thunder",
    element: "air",
    cost: 15
  }
}
map[ref:{181388642581742080 0xc420215ee0 <nil>} ts:1509244539709690 data:map[cost:15 element:air name:Mountainous Thunder]]
{
  "ref": { "@ref": "classes/spells/181388642581742080" },
  "class": { "@ref": "classes/spells" },
  "ts": 1509244539709690,
  "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
  }
}
{ ref:
  Ref(id=181388642581742080, collection=Ref(id=spells, collection=Ref(id=collections))),
  ts: 1527274715273882,
  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"))
  )
);
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)
}
System.out.println(
    serverClient.query(
        Create(
            Ref(Collection(Value("posts")), Value(1)),
            Obj(
                "data", Obj(
                    "title", Value("The first post")
                )
            )
        )
    ).get());
serverClient.query(
  q.Create(
    q.Ref(q.Collection('posts'), '1'),
    { data: { title: 'The first post' } },
  )
)
.then((ret) => console.log(ret))
print(serverClient.query(
  q.create(
    q.ref(q.collection("posts"), 1),
    {"data": {"title": "The first post"}}
  )
))
println(Await.result(
  serverClient.query(
    Create(
      Ref(Collection("posts"), 1),
      Obj("data" -> Obj("title" -> "The first post"))
    )
  ),
  5.seconds
))
ObjectV(ref: RefV(id = "1", collection = RefV(id = "posts", collection = RefV(id = "collections"))),ts: LongV(1587596508180000),data: ObjectV(title: StringV(The first post)))
{"object":{"data":{"object":{"title":"The first post"}},"ref":{"@ref":{"collection":{"@ref":{"collection":{"@ref":{"id":"collections"}},"id":"posts"}},"id":"1"}},"ts":1587596382540000}}
{ref: ref(id = "1", collection = ref(id = "posts", collection = ref(id = "collections"))), ts: 1587595695090000, data: {title: "The first post"}}
{
  ref: Ref(Collection("posts"), "1"),
  ts: 1587595447990000,
  data: { title: 'The first post' }
}
{'ref': Ref(id=1, collection=Ref(id=posts, collection=Ref(id=collections))), 'ts': 1587596259820000, 'data': {'title': 'The first post'}}
{ref: ref(id = "1", collection = ref(id = "posts", collection = ref(id = "collections"))), ts: 1587595971600000, data: {title: "The first post"}}

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!