DocumentReference
Represents a reference to a document in a database.
Path parts and field names must not contain forward slashes ( / ), and cannot start with underscores ( _ ) or dollar signs ($). Additionally, path parts cannot contain spaces. The total length of the document path cannot exceed 230 characters.
Attributes
Path
The path to this document reference in the database.
Id
The document ID of this document reference (e.g. item1 in path players/uid123/items/item1)
Parent
The parent collection reference if any.
Methods
Collection(string id)
Gets a reference to a sub-collection in this document.
Parameters:
string id: The ID of the collection in this document.
Returns: CollectionReference : A reference to the sub-collection.
Example
var itemsRef = database.Collection("players").Document("player123").Collection("items");;Possible exceptions
ArgumentException
If the ID is invalid or contains slashes (which can cause injection attacks).
Get()
Retrieves this document.
Returns: Task<Document> : The retrieved document.
Example
var playerRef = database.Collection("players").Document("player123");
var playerDocument = await playerRef.Get();
Debug.Log($"Retrieved player document ID: {playerDocument.Id}");Possible exceptions
ForbiddenException
NoAccess
The database rules forbid read access to this document.
NotFoundException
DatabaseNotFound
The database was not found.
Listen(Action<SingleDocumentChange> onData,
Action<Exception> onError,
Action onClosed,
bool autoReconnect = true,
bool sendInitialData = false)
Listens to changes to this document. Changes notified are only document update and inserts (no delete).
Parameters:
Action<SingleDocumentChange> onData: The callback when an update is received.Action<Exception> onError: The callback when an error is received.Action onClosed: The callback when the connection is closed and will not be restored.bool autoReconnect: Whether to automatically reconnect to the server when the internet connection drops.bool sendInitialData: Whether to send the document in its current state (if it exists) when the listener is first set up.
Returns: Func<Task> : A function to close the listener.
Example
locationARef.Listen(
onData: change =>
{
switch (change.Type)
{
case SingleDocumentChangeType.Initial:
/* When initial data is received, only change.Document is available. */
Debug.Log("Initial data received.");
break;
case SingleDocumentChangeType.Insert:
/* When an insert is received, only change.Document is available. */
Debug.Log("Document inserted.");
break;
case SingleDocumentChangeType.Update:
/* When an update is received, change.ChangeDescription and change.Document are available. */
var updatedFields = change.ChangeDescription!.UpdatedFields;
foreach (var field in updatedFields)
{
Debug.Log($"Field updated: {field.Key} = {field.Value}");
}
/* Handle the updated field as needed */
var deletedFields = change.ChangeDescription!.DeletedFields;
foreach (var field in deletedFields)
{
Debug.Log($"Field deleted: {field}");
}
/* Handle the deleted field as needed */
Debug.Log("Document updated.");
break;
}
},
onError: error =>
{
Debug.LogError($"Error listening to documents: {error.Message}");
/* Handle the error as needed */
},
onClosed: () =>
{
Debug.Log("Listener closed");
/* Handle the listener being closed, e.g. by the game or due to network issues */
},
autoReconnect: true,
sendInitialData: true
);Possible exceptions
ForbiddenException
NoAccess
The database rules forbid read access to this document.
NotFoundException
DatabaseNotFound
The database was not found.
Set(Dictionary<string, object> data)
Adds or replaces a document at this path.
Parameters:
Dictionary<string, object> data: The document data.
Example
var item1Ref = database.Collection("players").Document("player123").Collection("items").Document("item1");
await item1Ref.Set(new Dictionary<string, object>
{
{ "id", "sword" },
{ "acquiredDate", "2025-06-27" }
});Possible exceptions
BadRequestException
InvalidDocumentData
The document data is invalid (e.g. ID or field name is invalid).
ForbiddenException
NoAccess
The database rules forbid add access to this document.
NotFoundException
DatabaseNotFound
The database was not found.
Update(Dictionary<string, DocumentDataOperation> update)
Updates the data of this document.
Parameters:
Dictionary<string, DocumentDataOperation> update: The update specification, with field path as key and operation as value.
Example
var playerRef = database.Collection("players").Document("player123");
await playerRef.Update(new Dictionary<string, DocumentDataOperation>
{
{ "skillLevel", DocumentDataOperation.Inc(10) },
{ "matchesPlayed", DocumentDataOperation.Inc(1) }
});Possible exceptions
BadRequestException
InvalidField
The field path of a field being updated is invalid (e.g. accessing a field in a primitive).
You cannot rename fields in an array-embedded dictionary (e.g. renaming mylist.0.age to age)
InvalidUpdateDataType
The data type of the field being updated does not match the update operation (e.g. Inc operation on a field with a string value)
ForbiddenException
NoAccess
The database rules forbid update access to this document.
NotFoundException
DatabaseNotFound
The database was not found.
Delete()
Deletes this document.
Example
var item1Ref = database.Collection("players").Document("player123").Collection("items").Document("item1");
await item1Ref.Delete();Possible exceptions
ForbiddenException
NoAccess
The database rules forbid delete access to this document.
NotFoundException
DatabaseNotFound
The database was not found.
Last updated