Skip to main content
A DatabaseReference represents a specific path in the database. It provides methods for reading, writing, and querying data at that location. Obtain a reference via LarkDatabase.ref(). 
const ref = db.ref('users/alice');

​
Properties

PropertyTypeDescription
pathstringThe absolute path this reference points to.
keystring | nullThe last segment of the path, or null for the root reference.
parentDatabaseReference | nullA reference to the parent location, or null for the root.
rootDatabaseReferenceA reference to the root of the database.
databaseLarkDatabaseThe LarkDatabase instance this reference belongs to.
queryIdentifierstringA string that uniquely identifies the query parameters attached to this reference.

​
child

child(path: string): DatabaseReference
Returns a new DatabaseReference for a child location relative to this reference.
ParameterTypeDescription
pathstringA relative path from this location. Can contain multiple segments separated by /.
const usersRef = db.ref('users');
const aliceRef = usersRef.child('alice');
const profileRef = usersRef.child('alice/profile');

​
Write Methods

​
set

set(value: any): Promise<void>
Writes a value to this location, replacing any existing data.
ParameterTypeDescription
valueanyThe value to write. Can be a primitive, object, array, or null (which deletes the data).
await db.ref('users/alice').set({
  name: 'Alice',
  email: 'alice@example.com',
});

​
update

update(values: object): Promise<void>
Updates specific children at this location without overwriting the entire node. Supports multi-path updates with nested path keys.
ParameterTypeDescription
valuesobjectAn object containing the children to update.
await db.ref('users/alice').update({
  email: 'newalice@example.com',
  'profile/lastSeen': Date.now(),
});

​
remove

remove(): Promise<void>
Deletes the data at this location and all child locations. 
await db.ref('users/alice').remove();

​
push

push(value?: any): Promise<DatabaseReference>
Generates a new child location with a unique, chronologically-sortable key and optionally writes a value to it. Returns a reference to the new child.
ParameterTypeDescription
valueanyOptional value to write at the new child location.
const newPostRef = await db.ref('posts').push({
  title: 'Hello World',
  timestamp: ServerValue.TIMESTAMP,
});

console.log(newPostRef.key); // e.g. "-NxK3j..."
If you omit the value, push() returns a reference with the generated key without writing anything. You can then use set() on the returned reference.

​
setWithPriority

setWithPriority(value: any, priority: string | number | null): Promise<void>
Writes a value along with a priority for sorting.
ParameterTypeDescription
valueanyThe value to write.
prioritystring | number | nullThe sort priority.
await db.ref('scores/alice').setWithPriority({ score: 100 }, 100);

​
setPriority

setPriority(priority: string | number | null): Promise<void>
Sets the priority of data at this location without modifying the value.
ParameterTypeDescription
prioritystring | number | nullThe new priority.
await db.ref('scores/alice').setPriority(200);

​
Read Methods

​
once

once(eventType?: string): Promise<DataSnapshot>
Reads data from this location once. Does not subscribe to ongoing changes.
ParameterTypeDefaultDescription
eventTypestring'value'The event type to listen for. One of 'value', 'child_added', 'child_changed', 'child_removed', 'child_moved'.
const snapshot = await db.ref('users/alice').once();
console.log(snapshot.val());

​
get

get(): Promise<DataSnapshot>
Reads the data at this location once. Equivalent to once('value'). 
const snapshot = await db.ref('users/alice').get();
if (snapshot.exists()) {
  console.log(snapshot.val());
}

​
Subscription Methods

​
on

on(eventType: string, callback: (snapshot: DataSnapshot) => void): () => void
Subscribes to data changes at this location. The callback fires immediately with the current value and again whenever the data changes. Returns an unsubscribe function.
ParameterTypeDescription
eventTypestringThe event type to listen for.
callbackFunctionCalled with a DataSnapshot each time the event fires.
Event types:
EventDescription
'value'Fires when the data at this location (including children) changes.
'child_added'Fires for each existing child and when a new child is added.
'child_changed'Fires when a child’s data changes.
'child_removed'Fires when a child is removed.
'child_moved'Fires when a child’s sort order changes.
const unsubscribe = db.ref('users').on('child_added', (snapshot) => {
  console.log(`User added: ${snapshot.key}`, snapshot.val());
});

// Stop listening
unsubscribe();

​
Query Methods

All query methods return a new DatabaseReference with query constraints attached. They do not modify the original reference.

​
orderByChild

orderByChild(path: string): DatabaseReference
Orders results by the value of a specified child key.
ParameterTypeDescription
pathstringThe child key to order by. Can be a nested path (e.g. 'profile/age').
const byAge = db.ref('users').orderByChild('age').limitToFirst(10);

​
orderByKey

orderByKey(): DatabaseReference
Orders results by their key. 
const byKey = db.ref('users').orderByKey();

​
orderByValue

orderByValue(): DatabaseReference
Orders results by their value. Useful when children are primitives. 
const byScore = db.ref('scores').orderByValue().limitToLast(5);

​
orderByPriority

orderByPriority(): DatabaseReference
Orders results by their priority. 
const byPriority = db.ref('tasks').orderByPriority();

​
limitToFirst

limitToFirst(limit: number): DatabaseReference
Limits the result set to the first N items (based on the current ordering).
ParameterTypeDescription
limitnumberMaximum number of items to return from the beginning.
const firstFive = db.ref('posts').orderByKey().limitToFirst(5);

​
limitToLast

limitToLast(limit: number): DatabaseReference
Limits the result set to the last N items (based on the current ordering).
ParameterTypeDescription
limitnumberMaximum number of items to return from the end.
const lastTen = db.ref('posts').orderByKey().limitToLast(10);

​
startAt

startAt(value: any, key?: string): DatabaseReference
Returns items starting at the specified value (inclusive).
ParameterTypeDescription
valueanyThe value to start at.
keystringOptional key to further filter when multiple children have the same value.
const adults = db.ref('users').orderByChild('age').startAt(18);

​
startAfter

startAfter(value: any, key?: string): DatabaseReference
Returns items starting strictly after the specified value (exclusive).
ParameterTypeDescription
valueanyThe value to start after.
keystringOptional key for further filtering.
const olderThan18 = db.ref('users').orderByChild('age').startAfter(18);

​
endAt

endAt(value: any, key?: string): DatabaseReference
Returns items ending at the specified value (inclusive).
ParameterTypeDescription
valueanyThe value to end at.
keystringOptional key for further filtering.
const upTo30 = db.ref('users').orderByChild('age').endAt(30);

​
endBefore

endBefore(value: any, key?: string): DatabaseReference
Returns items ending strictly before the specified value (exclusive).
ParameterTypeDescription
valueanyThe value to end before.
keystringOptional key for further filtering.
const under30 = db.ref('users').orderByChild('age').endBefore(30);

​
equalTo

equalTo(value: any, key?: string): DatabaseReference
Returns only items matching the specified value exactly.
ParameterTypeDescription
valueanyThe value to match.
keystringOptional key for further filtering.
const admins = db.ref('users').orderByChild('role').equalTo('admin');

​
Other Methods

​
onDisconnect

onDisconnect(): OnDisconnect
Returns an OnDisconnect object that lets you register write operations to be performed on the server if the client disconnects. 
const presenceRef = db.ref('status/alice');
presenceRef.onDisconnect().set('offline');
await presenceRef.set('online');

​
transaction

transaction(updateFn: (currentValue: any) => any): Promise<TransactionResult>
Atomically reads and modifies data at this location. The updateFn receives the current value and returns the desired new value. If another client writes concurrently, the function is retried with the updated value.
ParameterTypeDescription
updateFn(currentValue: any) => anyA function that takes the current value and returns the new value. Return undefined to abort.
const result = await db.ref('counters/likes').transaction((current) => {
  return (current || 0) + 1;
});

console.log(result.committed); // true if the transaction succeeded
console.log(result.snapshot.val()); // the final value