When onDocumentCreated is triggered for a nested document, the parent document has not been created yet

[dandv]

When onDocumentCreated is triggered for a nested document like /countries/{countryId}/cities/{cityId}, its parents, here the /countries/{countryId} document, should already exist, as suggested by the documentation (see the Expected behavior section). But tests show that if the country document didn't already exist (i.e. when creating the first city within it), it won't already exist at the time the trigger executes.

Related issues

None.

[REQUIRED] Version info

node: v22.12.0

firebase-functions: 6.2.0

firebase-tools: 13.29.1

firebase-admin: 13.0.2

[REQUIRED] Test case

https://github.com/dandv/onDocumentCreated-parent-bug

[REQUIRED] Steps to reproduce

git clone https://github.com/dandv/onDocumentCreated-parent-bug.git
cd onDocumentCreated-parent-bug
npm install
cd functions
npm deploy
node create-doc.js  # should see "Done"

Check the logs at https://console.cloud.google.com/logs/query?project=ondocumentcreated-bug
and countryDoc.exists: false (screenshot below).

[REQUIRED] Expected behavior

Given that the city document does exist (see the screenshot) when the trigger starts execution, the parent document (/countries/USA) should already exist, as the documentation states:

Collections and documents are created implicitly in Cloud Firestore.
Simply assign data to a document within a collection.
If either the collection or document does not exist, Cloud Firestore creates it.

The Trigger a function when a new document is created example doesn't mention anything about the parent document of newly created nested documents not existing yet.

If the code is somehow WAI, then the documentation should be updated to mention this counter-intuitive behavior specifically.

[REQUIRED] Actual behavior

The output above is produced by the code below:

exports.firestoreEventHander = onDocumentCreated(
    "countries/{countryId}/cities/{cityId}",
    async (event) => {
      console.log("onDocumentCreated called with", event);

      const snapshot = event.data;
      console.log("snapshot:", snapshot.data());
      console.log("snapshot exists:", snapshot.exists);  // true

      const cityId = snapshot.id;
      console.log("cityId:", cityId);

      const countryRef = snapshot.ref.parent.parent;
      const countryId = countryRef.id;
      const countryPath = countryRef.path;
      console.log("countryId:", countryId);
      console.log("country path:", countryPath); // countries/USA

      // Access snapshot through the db
      const cityDoc = await db.doc(`countries/${countryId}/cities/${cityId}`).get();
      console.log("cityDoc via db:", cityDoc.data());
      console.log("cityDoc.exists:", cityDoc.exists);  // true

      // Check if the countryRef document exists
      const countryDoc = await countryRef.get();
      console.log("countryDoc:", countryDoc.data());  // ⚠️ undefined ⚠️
      console.log("countryDoc.exists:", countryDoc.exists);  // ⚠️ false ⚠️

      // Try to access the country via db.doc()
      const countryDoc2 = await db.doc(`countries/${countryId}`).get();
      console.log("countryDoc2:", countryDoc2.data());  // ⚠️ undefined ⚠️
      console.log("countryDoc2.exists:", countryDoc2.exists);  // ⚠️ false ⚠️
    },
);

Were you able to successfully deploy your functions?

Yes, the function was deployed without errors, and is triggered as seen in the screenshot above.

[google-oss-bot]

I couldn't figure out how to label this issue, so I've labeled it for a human to triage. Hang tight.