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, 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

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.

client.Query(
    Create(
        Collection("spells"),
        Obj(
            "data", Obj(
                "name", "Mountainous Thunder",
                "element", "air",
                "cost", 15
            )
        )
    )
);
ObjectV(ref: RefV(id = "280491264236847616", collection = RefV(id = "spells", collection = RefV(id = "collections"))),ts: LongV(1603756164680000),data: ObjectV(name: StringV(Mountainous Thunder),element: StringV(air),cost: LongV(15)))
result, err := client.Query(
	f.Create(
		f.Collection("spells"),
		f.Obj{
			"data": f.Obj{
				"name": "Mountainous Thunder",
				"element": "air",
				"cost": 15 }}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:map[cost:15 element:air name:Mountainous Thunder] ref:{280481791726322176 0xc00009a1b0 0xc00009a1b0 <nil>} ts:1603747130990000]
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 = "269699776491028992", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1593464599990000, 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))
.catch((err) => console.error('Error: %s', err))
{
  ref: Ref(Collection("spells"), "268159557092508160"),
  ts: 1591995732300000,
  data: { name: 'Mountainous Thunder', element: 'air', cost: 15 }
}
result = client.query(
  q.create(
    q.collection("spells"),
    {
      "data": {
        "name": "Mountainous Thunder",
        "element": "air",
        "cost": 15
      }
    }
  )
)
print(result)
{'ref': Ref(id=269062149575279104, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1592856511570000, '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(id = "270769674127409664", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1594484933880000, 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"}}

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!