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

A reference to the document that was created.

data

Object

The data that was inserted with the document.

ts

Long

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.

try
{
    Value result = await client.Query(
        Create(
            Collection("spells"),
            Obj(
                "data", Obj(
                    "name", "Mountainous Thunder",
                    "element", "air",
                    "cost", 15
                )
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
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("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}}
try {
  println(Await.result(
    client.query(
  Create(
    Collection("spells"),
    Obj(
      "data" -> Obj(
        "name" -> "Mountainous Thunder",
        "element" -> "air",
        "cost" -> 15
      )
    ))),
    5.seconds
  ))
} catch {
  case unknown: Throwable => println("Error: " + unknown.getMessage())
}
{ref: ref(id = "270769674127409664", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1594484933880000, data: {name: "Mountainous Thunder", element: "air", cost: 15}}
Create(
  Collection('spells'),
  {
    data: {
      name: 'Mountainous Thunder',
      element: 'air',
      cost: 15,
    },
  },
)
{
  ref: Ref(Collection("spells"), "302043888864985600"),
  ts: 1624310349250000,
  data: { name: 'Mountainous Thunder', element: 'air', cost: 15 }
}
Query metrics:

  •    bytesIn:  131

  •   bytesOut:  224

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:    0

  • writeBytes:  650

  •  queryTime: 32ms

  •    retries:    0

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

try
{
    Value result = await serverClient.Query(
        Create(
            Ref(Collection("Posts"), 1),
            Obj("data", Obj("title", "The first post"))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "1", collection = RefV(id = "Posts", collection = RefV(id = "collections"))),ts: LongV(1622574261840000),data: ObjectV(title: StringV(The first post)))
result, err := serverClient.Query(
	f.Create(
		f.Ref(f.Collection("Posts"), "1"),
		f.Obj{"data": f.Obj{"title": "The first post"}}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:map[title:The first post] ref:{1 0xc00009dbc0 0xc00009dbc0 <nil>} ts:1622574332010000]
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: 1622574416990000, 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))
.catch((err) => console.error('Error: %s', err))
{
  ref: Ref(Collection("Posts"), "1"),
  ts: 1622574501060000,
  data: { title: 'The first post' }
}
result = serverClient.query(
  q.create(
    q.ref(q.collection("Posts"), 1),
    {"data": {"title": "The first post"}}
  )
)
print(result)
{'ref': Ref(id=1, collection=Ref(id=Posts, collection=Ref(id=collections))), 'ts': 1622574508850000, 'data': {'title': 'The first post'}}
try {
  println(Await.result(
  serverClient.query(
    Create(
      Ref(Collection("Posts"), 1),
      Obj("data" -> Obj("title" -> "The first post"))
    )
  ),
  5.seconds
))} catch {
  case unknown: Throwable => println("Error: " + unknown.getMessage())
}
{ref: ref(id = "1", collection = ref(id = "Posts", collection = ref(id = "collections"))), ts: 1622574722430000, data: {title: "The first post"}}
Create(
  Ref(Collection('Posts'), '1'),
  { data: { title: 'The first post' } },
)
{
  ref: Ref(Collection("Posts"), "1"),
  ts: 1624310598180000,
  data: { title: 'The first post' }
}
Query metrics:

  •    bytesIn:  117

  •   bytesOut:  176

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:   14

  • writeBytes:  352

  •  queryTime: 23ms

  •    retries:    0

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!