Docs: Addressables local→remote dependency example (#67)

Add SQLite example query and narrative for finding explicit addressables in
locally classified bundles that depend on explicit addressables in remote
bundles, using build layout JSON from analyze.

Update addressables-build-reports schema notes and cross-link to the example.

Author: timt-unity3d

Documentation/addressables-build-reports.md

@@ -51,14 +51,14 @@ Contains groups used in the build and whether they're pack separate or together.
 
 #### `addressables_build_group_schemas`
 Map groups to their schemas
-  * schema_rid maps to addressables_group_schemas.id
+  * schema_rid maps to addressables_build_schemas.id
   * group_id maps to addressables_build_groups.id
 
 #### `addressables_build_schemas`
 Contain schema names.
-  * id maps to addressables_group_schemas.id
+  * id is referenced by `addressables_build_group_schemas.schema_rid` and `addressables_build_schema_data_pairs.schema_id`
 
-#### `add_build_schema_data_pairs`
+#### `addressables_build_schema_data_pairs`
 Contains key value pairs of schema settings at time of build.
   * schema_id maps to addressables_build_schemas.id
 
@@ -83,8 +83,8 @@ Explicit assets (marked as Addressable). Has Addressable name and asset informat
 
 #### `addressables_build_explicit_asset_internal_referenced_other_assets`
 Map explicit assets to other assets they refer to. For instance a prefab to its underlying FBX
-  * referencing_asset_rid maps to addressables_build_explicit_assets.id
-  * data_from_other_asset_Id maps to addressables_build_data_from_other_assets.id
+  * explicit_asset_id maps to addressables_build_explicit_assets.id
+  * internal_referenced_other_asset_rid maps to addressables_build_data_from_other_assets.id
 
 #### `addressables_build_data_from_other_assets`
 Assets added into the build implicitly by explicitly defined assets.
@@ -110,6 +110,10 @@ UnityDataTools.exe "C:\\Temp\\MyExtractedFiles" -o "addressables_analysis.db" -p
 
 You can analyze a directory with both asset bundles (*.bundle) and json files (*.json) at the same time.
 
+### Cross-group dependencies (local → remote)
+
+To find explicit addressable assets whose bundle is classified as **local** (for example by `load_path`) but that depend on explicit addressables in **remote** bundles, see [Example: Local Addressable groups depending on remote groups](analyze-examples.md#example-local-addressable-groups-depending-on-remote-groups) in analyze-examples.md.
+
 ### Sample Queries
 
 Once the data is in the database, you can run queries to analyze your Addressables build:
@@ -118,12 +122,12 @@ Once the data is in the database, you can run queries to analyze your Addressabl
 #### Find all implicit assets for an explicit asset
 ```sql
 -- Find implicitly included assets for a given explicit asset id
-SELECT a.explicit_asset_id, b.id, b.asset_path, b.asset_path 
-  FROM addressables_build_explicit_asset_internal_referenced_other_assets a, 
+SELECT a.explicit_asset_id, b.id, b.asset_path
+  FROM addressables_build_explicit_asset_internal_referenced_other_assets a,
        addressables_build_data_from_other_assets b
- WHERE a.internal_referenced_other_asset_rid = b.id 
-   AND a.build_id = b.build_id;
-   AND a.explicit_asset_id = 5092 
+ WHERE a.internal_referenced_other_asset_rid = b.id
+   AND a.build_id = b.build_id
+   AND a.explicit_asset_id = 5092
    AND a.build_id = 3;
 ```
 

Documentation/analyze-examples.md

@@ -68,6 +68,8 @@ Shader Graphs/CustomLightingBuildingsB      113.4 KB     1b2fdfe013c58ffd57d7663
 
 See [buildreport.md](buildreport.md) for information about using analyze to look at BuildReport files.
 
+
+
 ## Example: Using AI tools to help write queries
 
 This is not a tutorial on using AI tools.  However one useful tip:
@@ -261,3 +263,94 @@ Examples of alternative sources of build information:
 * The Editor log reports a lot of information during a build. 
 * Regular AssetBundle builds create [.manifest files](https://docs.unity3d.com/Manual/assetbundles-file-format.html), which contain information about the source assets and types.
 * Addressable builds do not produce BuildReport files, nor .manifest files. But UnityDataTools supports analyzing the [Addressables Build Reports](addressables-build-reports.md) and will populate the `addressables_build_explicit_assets` and `addressables_build_data_from_other_assets` tables.
+
+## Example: Local Addressable groups depending on remote groups
+
+A common scenario when working with remote content, is to add a new piece of content to a local Addressable group that depends upon content in a remote Addressable group. Often this is fine, but if it's unexpected it can lead to the game stalling while downloading a large quantity of remote content. This example prints out content in local Addressable groups that depend upon content in remote groups.
+
+UnityDataTools does **not** store a boolean “local” or “remote” flag. Each bundle row has a **`load_path`** string (table `addressables_build_bundles`). You can classify bundles for a given project by testing that string—for example:
+
+* **Remote bundle:** `load_path` starts with `https://` or `http://` (typical for remote profiles).
+* **Local bundle:** not matched by the above (often paths containing `{UnityEngine.AddressableAssets.Addressables.RuntimePath}` or similar). You may refine this for your naming or add conditions such as non-empty `load_path` if you need to exclude odd rows.
+
+In this case, we want to know about both explicitly referenced assets and implicitly referenced assets. Explicitly referenced assets are assets that you have directly linked in another bundle, while implicitly referenced assets are dependencies of your source asset. For example, a prefab in a local group may explicitly reference a material in a remote group.
+
+**1. Produce a database from your build reports** (adjust paths; on Windows use backslashes or quoted paths):
+
+```
+UnityDataTool analyze "C:\YourProject\Library\com.unity.addressables\BuildReports" -o addressables_analysis.db
+```
+
+**2. Find the `build_id`** for the report you care about (often the latest row):
+
+```
+sqlite3 addressables_analysis.db "SELECT id, name, start_time FROM addressables_builds ORDER BY id DESC LIMIT 5;"
+```
+
+Use that `id` as `:build_id` in the query below.
+
+**3. List explicit assets in a local bundle that reference an explicit asset in a remote bundle**
+
+The following uses a `UNION ALL` of the two explicit-explicit edge tables. Bundle `load_path` values are joined only so the `WHERE` clause can classify local vs remote bundles; they are not selected in the result. Column aliases **`local_*`** refer to the asset in the locally classified bundle (the referencing side), and **`remote_*`** to the depended-on asset in the remotely classified bundle. The **`dependency_type`** column uses short labels aligned with typical Addressables UI wording: **`explicit`** for edges from **ExternallyReferencedAssets**, and **`implicit`** for edges from **InternalReferencedExplicitAssets**. In both cases the dependency is still between **explicit addressables** in the build layout; non-addressable “other” assets are modeled separately in `addressables_build_explicit_asset_internal_referenced_other_assets` / `addressables_build_data_from_other_assets`.
+
+```sql
+SELECT
+  'explicit' AS dependency_type,
+  src.addressable_name AS local_address,
+  src.asset_path AS local_asset_path,
+  sg.name AS local_group_name,
+  tgt.addressable_name AS remote_address,
+  tgt.asset_path AS remote_asset_path,
+  tg.name AS remote_group_name
+FROM addressables_build_explicit_asset_externally_referenced_assets x
+JOIN addressables_build_explicit_assets src
+  ON src.id = x.explicit_asset_id AND src.build_id = x.build_id
+JOIN addressables_build_explicit_assets tgt
+  ON tgt.id = x.externally_referenced_asset_rid AND tgt.build_id = x.build_id
+JOIN addressables_build_bundles sb
+  ON sb.id = src.bundle AND sb.build_id = src.build_id
+JOIN addressables_build_bundles tb
+  ON tb.id = tgt.bundle AND tb.build_id = tgt.build_id
+JOIN addressables_build_groups sg
+  ON sg.guid = src.group_guid AND sg.build_id = src.build_id
+JOIN addressables_build_groups tg
+  ON tg.guid = tgt.group_guid AND tg.build_id = tgt.build_id
+WHERE x.build_id = :build_id
+  AND NOT (COALESCE(sb.load_path, '') LIKE 'https://%' OR COALESCE(sb.load_path, '') LIKE 'http://%')
+  AND (COALESCE(tb.load_path, '') LIKE 'https://%' OR COALESCE(tb.load_path, '') LIKE 'http://%')
+
+UNION ALL
+
+SELECT
+  'implicit' AS dependency_type,
+  src.addressable_name AS local_address,
+  src.asset_path AS local_asset_path,
+  sg.name AS local_group_name,
+  tgt.addressable_name AS remote_address,
+  tgt.asset_path AS remote_asset_path,
+  tg.name AS remote_group_name
+FROM addressables_build_explicit_asset_internal_referenced_explicit_assets iref
+JOIN addressables_build_explicit_assets src
+  ON src.id = iref.explicit_asset_id AND src.build_id = iref.build_id
+JOIN addressables_build_explicit_assets tgt
+  ON tgt.id = iref.internal_referenced_explicit_asset_rid AND tgt.build_id = iref.build_id
+JOIN addressables_build_bundles sb
+  ON sb.id = src.bundle AND sb.build_id = src.build_id
+JOIN addressables_build_bundles tb
+  ON tb.id = tgt.bundle AND tb.build_id = tgt.build_id
+JOIN addressables_build_groups sg
+  ON sg.guid = src.group_guid AND sg.build_id = src.build_id
+JOIN addressables_build_groups tg
+  ON tg.guid = tgt.group_guid AND tg.build_id = tgt.build_id
+WHERE iref.build_id = :build_id
+  AND NOT (COALESCE(sb.load_path, '') LIKE 'https://%' OR COALESCE(sb.load_path, '') LIKE 'http://%')
+  AND (COALESCE(tb.load_path, '') LIKE 'https://%' OR COALESCE(tb.load_path, '') LIKE 'http://%');
+```
+
+To print results from the command line, save the query to a file (e.g. `query.sql`) and run:
+
+```
+sqlite3 addressables_analysis.db ".mode column" ".headers on" ".param set :build_id 1" ".read query.sql"
+```
+
+Replace `1` with the `build_id` value found in step 2.