Skip to content
CARP Documentation

DocumentReference

A reference to a JSON document in a CAWS collection, used to write, read or delete it.

Obtained from CarpService.document, CarpService.documentById or CollectionReference.document. The document may or may not exist yet; setData creates it (and its collection) if needed.

A DocumentReference can also be used to create a CollectionReference to a sub-collection.

final ref = CarpService().collection('users').document('alice');
await ref.setData({'email': 'alice@example.com'});
final snapshot = await ref.get();
Inheritance

Properties

cawsPath

String get cawsPath

The full CARP Web Service (CAWS) path to this document.

If the id of this document is known, use the documents CARP endpoint, otherwise use the collections endpoint.

documentUri

String get documentUri

The full URI for the document endpoint for this document.

id

int? get id

The unique server-side id of this document. Returns null if the id is unknown, i.e. not yet read from the server.

name

String get name

The name of this document.

path

String get path

The path to this document

studyId

String get studyId

The id of the study for this document.

Methods

collection

CollectionReference collection(
  1. String name
)

Returns the reference of a collection contained inside of this document.

delete

Future<void> delete()

Deletes the document referred to by this DocumentReference.

If the document ID is not known, looks the document up first and returns without deleting if it does not exist. If the ID is known, the DELETE is sent directly and server errors, including not found, are thrown.

get

Future<DocumentSnapshot?> get()

Reads the document referenced by this DocumentReference and updates id.

If no document exists, the read will return null.

rename

  1. @Deprecated('Documents cannot be renamed in CAWS.')
Future<DocumentSnapshot> rename(
  1. String name
)

Renames the document referred to by this DocumentReference.

setData

Future<DocumentSnapshot> setData(
  1. Map<String, dynamic> data
)

Writes data to the document referred to by this DocumentReference.

If id is unknown, a new document is created (and its collection, if needed). Otherwise the document is replaced via updateData. Returns a DocumentSnapshot with the ID generated at the server side.

toString

String toString()
override

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

updateData

Future<DocumentSnapshot> updateData(
  1. Map<String, dynamic> data
)

Replaces the data of the document referred to by this DocumentReference with data.

Throws a CarpServiceException if no document exists yet.