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 has the document data and optional metadata.

Parameters

Parameter Type Definition and Requirements

collection

String or Reference

The name, or Reference, of the collection that should have 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

An object with the fields and values for this document.

credentials

Object

Optional - The permissions for this document.

delegates

Array

Optional - An array of References that should be used for access control instead of this document. See delegates in the Security reference.

ttl

Timestamp

Optional - A timestamp that indicates the time-to-live for a document, which is when the document is removed from the collection and can’t be queried. The document history can continue to be accessed using the Events function, provided the events are in the history retention interval and the document reference is input to the Events function.

Returns

A document with the data and metadata about the results of the operations.

Field Name Field Type Definition and Requirements

ref

Reference

A reference to the created document.

data

Object

The created document data.

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 has 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] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  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}}
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 defined document ID (using 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] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  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'}}
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

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!