FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

CreateRole

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
CreateRole( param_object )
create_role( param_object )
CreateRole( param_object )
CreateRole( param_object )
CreateRole( param_object )
CreateRole( param_object )

Description

CreateRole creates a new user-defined role with the specified param_object. This function requires an admin key for authentication.

The maximum number of overlapping roles is 64. When you attempt to create the 65th overlapping role, you get an error when calling the CreateRole function.

Parameters

Parameter Type Definition and requirements

param_object

Object

The param_object fields are described below.

param_object

Field name Field type Definition and requirements

name

String

The role’s name.

Cannot be events, sets, self, documents, or _. Cannot have the % character.

privileges

Array

One or more privilege configuration objects.

membership

Array

Optional. One or more membership configuration objects.

data

Object

Optional - Contains user-defined metadata for the role. It is provided for the developer to store role-relevant information.

Returns

An object containing the metadata about the results of CreateRole operations.

Field name Field type Definition and requirements

ref

Reference

The Reference is an automatically-generated, unique identifier within the database to the role that was created.

ts

Long

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

name

String

The role’s name.

privileges

Array

The role’s privileges configuration.

membership

Array

The role’s membership configuration.

Examples

The following query creates a role that grants unrestricted read access to the spells collection:

client.query(
  q.CreateRole({
    name: 'new-role',
    privileges: {
      resource: q.Collection('spells'),
      actions: { read: true },
    },
  })
)
.then((result) => console.log(result))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Role("new-role"),
  ts: 1592053955060000,
  name: 'new-role',
  privileges: { resource: Collection("spells"), actions: { read: true } }
}
result = client.query(
  q.create_role({
    "name": "new-role",
    "privileges": {
      "resource": q.collection("spells"),
      "actions": {"read": True}
    }
  })
)
print(result)
{'ref': Ref(id=new-role, collection=Ref(id=roles)), 'ts': 1592856253820000, 'name': 'new-role', 'privileges': {'resource': Ref(id=spells, collection=Ref(id=collections)), 'actions': {'read': True}}}
result, err := client.Query(
	f.CreateRole(
		f.Obj{
			"name": "new-role",
			"privileges": f.Obj{
				"resource": f.Collection("spells"),
				"actions": f.Obj{"read": true}}}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[name:new-role privileges:map[actions:map[read:true] resource:{spells 0xc000162240 0xc000162240 <nil>}] ref:{new-role 0xc0001620f0 0xc0001620f0 <nil>} ts:1603747138280000]
try
{
    Value result = await client.Query(
        CreateRole(
            Obj(
                "name", "new-role",
                "privileges", Obj(
                    "resource", Collection("spells"),
                    "actions", Obj("read", true)
                )
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "new-role", collection = RefV(id = "roles")),ts: LongV(1603756193250000),name: StringV(new-role),privileges: ObjectV(resource: RefV(id = "spells", collection = RefV(id = "collections")),actions: ObjectV(read: BooleanV(True))))
System.out.println(
    client.query(
        CreateRole(
            Obj(
                "name", Value("new-role"),
                "privileges", Obj(
                    "resource", Collection("spells"),
                    "actions", Obj("read", Value(true))
                )
            )
        )
    ).get());
{ref: ref(id = "new-role", collection = ref(id = "roles")), ts: 1593464662230000, name: "new-role", privileges: {resource: ref(id = "spells", collection = ref(id = "collections")), actions: {read: true}}}
CreateRole({
  name: 'new-role',
  privileges: {
    resource: Collection('spells'),
    actions: { read: true },
  },
})
{
  ref: Role("new-role"),
  ts: 1624310368930000,
  name: 'new-role',
  privileges: { resource: Collection("spells"), actions: { read: true } }
}
Query metrics:

  •    bytesIn:  142

  •   bytesOut:  242

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:   91

  • writeBytes:  373

  •  queryTime: 43ms

  •    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!