Docs: include/exclude node based on fqn

[pankajastro]

Document the fqn include/exclude option introduced in PR: #2328 and #2375

[Copilot]

Pull request overview

This PR documents the new fqn (fully qualified name) selector option that was introduced in PR #2328 to fix an issue where dbt models with the same name as their parent folder couldn't be properly selected. The documentation adds a description of the new selector type and provides an example of how to use it.

Changes:

• Added documentation for the fqn: selector option to the list of available selectors
• Added a code example demonstrating how to use the fqn: selector in a DbtDag configuration
• Removed an unnecessary blank line in the documentation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.90%. Comparing base (b48b9f5) to head (f2421d5).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2371      +/-   ##
==========================================
+ Coverage   95.74%   97.90%   +2.16%     
==========================================
  Files         102      102              
  Lines        6885     6885              
==========================================
+ Hits         6592     6741     +149     
+ Misses        293      144     -149     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tatiana]

@pankajastro the changes we introduced in #2328 only affected Cosmos task execution, and not Cosmos custom selectors that are used with LoadMode.MANIFEST and LoadMode.CUSTOM to decide which nodes will be rendered in the DAG, to define its topology.

Therefore, this change in the documentation is not accurate. If users attempted to do the following on a project loaded with LoadMode.MANIFEST, Cosmos would error:

DbtDag(
    ...
    select=["fqn:my_dbt_project.analytics.tables.my_model"]
)

For the feature you're documenting to work, we'd need to modify:
https://github.com/astronomer/astronomer-cosmos/blob/main/cosmos/dbt/selector.py

While this change would not be very complex, I'd say it is a new feature that would need to be implemented. One aspect for this feature would be to make sure we analyse a few manifest files to confirm the representation of the fqn field.

As an example, I just checked a local manifest, and I observed it looked like this:

  "nodes": {
    "model.BIC_C5.AcctC5LuTrnf_C5HHAct_stg": {
      "resource_type": "model",
      "unique_id": "model.BIC_C5.AcctC5LuTrnf_C5HHAct_stg",
      "database": "SANDBOX",
      "schema": "TATIANAALCHUEYR",
      "name": "AcctC5LuTrnf_C5HHAct_stg",
      "package_name": "BIC_C5",
      "fqn": [
        "BIC_C5",
        "AcctC5LuTrnf",
        "AcctC5LuTrnf_C5HHAct_stg"
      ]

Which means we'd need to join the list in each model's "fqn". Something to test would also be whether dbt supports relative fqn paths.

Therefore, I suggest we close this PR for now and log a ticket to add this feature.

[pankajastro]

@pankajastro the changes we introduced in #2328 only affected Cosmos task execution, and not Cosmos custom selectors that are used with LoadMode.MANIFEST and LoadMode.CUSTOM to decide which nodes will be rendered in the DAG, to define its topology.

Therefore, this change in the documentation is not accurate. If users attempted to do the following on a project loaded with LoadMode.MANIFEST, Cosmos would error:

DbtDag(
    ...
    select=["fqn:my_dbt_project.analytics.tables.my_model"]
)

For the feature you're documenting to work, we'd need to modify: https://github.com/astronomer/astronomer-cosmos/blob/main/cosmos/dbt/selector.py

While this change would not be very complex, I'd say it is a new feature that would need to be implemented. One aspect for this feature would be to make sure we analyse a few manifest files to confirm the representation of the fqn field.

As an example, I just checked a local manifest, and I observed it looked like this:

  "nodes": {
    "model.BIC_C5.AcctC5LuTrnf_C5HHAct_stg": {
      "resource_type": "model",
      "unique_id": "model.BIC_C5.AcctC5LuTrnf_C5HHAct_stg",
      "database": "SANDBOX",
      "schema": "TATIANAALCHUEYR",
      "name": "AcctC5LuTrnf_C5HHAct_stg",
      "package_name": "BIC_C5",
      "fqn": [
        "BIC_C5",
        "AcctC5LuTrnf",
        "AcctC5LuTrnf_C5HHAct_stg"
      ]

Which means we'd need to join the list in each model's "fqn". Something to test would also be whether dbt supports relative fqn paths.

Therefore, I suggest we close this PR for now and log a ticket to add this feature.

Thanks for the review and pointing out this issue, @tatiana. I have drafted PR: #2375 to address it

[tatiana]

Thanks, @pankajastro , for implementing the feature, happy to merge the docs now!