docs: add examples tying the various data loaders and explain their hierarchy

[ad-claw000]

Summary: Added an example python script to explain how the various CSVParser DataLoaders and ParallelLoader fit together, answering user confusion about the SDK.

Verification: Executed tests. Updated examples/README.md.

Fixes #286.

[Copilot]

Pull request overview

Adds a new “loaders_101” example intended to clarify how ApertureDB’s Subscriptable-based CSV DataLoaders relate to ParallelLoader, and links it from the examples index.

Changes:

• Document a new example script in examples/README.md.
• Add examples/loaders_101/data_loader_hierarchy.py describing the loader hierarchy and demonstrating ParallelLoader.ingest() with multiple loaders.

Reviewed changes

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

File	Description
examples/README.md	Adds the new hierarchy example to the loaders_101 table.
examples/loaders_101/data_loader_hierarchy.py	New example script explaining loader hierarchy and attempting an end-to-end ingestion flow.

Comments suppressed due to low confidence (2)

examples/loaders_101/data_loader_hierarchy.py:76

• The entity_class= / name= / age= kwargs here are misleading: EntityDataCSV doesn’t use them to map columns, and it derives the class from the CSV’s EntityClass column. With the current persons.csv shape this call will fail validation. Adjust the example to match EntityDataCSV’s expected CSV schema rather than passing unused kwargs.

    print("Loading Entities...")
    # By providing the kwargs like `name`, `age`, we map the columns to properties.
    person_loader = EntityDataCSV("persons.csv", entity_class="Person", name="name", age="age")
    loader.ingest(person_loader)

examples/loaders_101/data_loader_hierarchy.py:95

• The kwargs passed to ConnectionDataCSV here (connection_class, src_class, dst_class, etc.) are not used by the loader (they’re ignored by CSVParser.__init__), and the loader instead derives class/key info from the CSV header (e.g., Person@name). This example will fail unless the CSV header is in the required ConnectionClass,<SrcClass>@<key>,<DstClass>@<key>,... format, and note that ImageDataCSV does not store the url column as a property when it is used as the source column, so dst_prop_key="url" won’t match anything unless you add a separate property column for it.

    connection_loader = ConnectionDataCSV(
        "connections.csv",
        connection_class="HasImage",
        src_class="Person",
        dst_class="Image",
        src_prop_key="name",     # Match the 'name' column in persons to 'src_name'
        src_prop_val="src_name",
        dst_prop_key="url",      # Match the 'url' column in images to 'dst_url'
        dst_prop_val="dst_url",
        connection_property="connection_property"
    )

---

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (3)

examples/loaders_101/data_loader_hierarchy.py:79

• The example suggests passing entity_class="Person", name="name", age="age" to map columns, but CSVParser/EntityDataCSV ignore these kwargs (only df, use_dask, blobs_relative_to_csv, etc. are handled) and EntityDataCSV uses the CSV headers directly. Remove these kwargs and rely on the CSV columns (EntityClass, property columns, constraint_...) to define the ingest.

    # By providing the kwargs like `name`, `age`, we map the columns to properties.
    person_loader = EntityDataCSV(
        "persons.csv", entity_class="Person", name="name", age="age")
    loader.ingest(person_loader)

examples/loaders_101/data_loader_hierarchy.py:84

• ImageDataCSV("images.csv", source="source"): the source kwarg is not a supported parameter for ImageDataCSV/CSVParser and will be ignored, which makes the example misleading. Instead, put source in the CSV as a property column (which you already do) and instantiate ImageDataCSV without that kwarg (or pass supported args like check_image).

    print("Loading Images...")
    image_loader = ImageDataCSV("images.csv", source="source")
    loader.ingest(image_loader)

examples/loaders_101/data_loader_hierarchy.py:98

• The ConnectionDataCSV(...) call passes kwargs like connection_class, src_class, dst_class, src_prop_key, etc., but ConnectionDataCSV does not accept/consume these; it derives connection class and endpoints entirely from the CSV columns/values. As written this will still fail validation due to the CSV header format. Remove these kwargs and update the CSV headers/columns to the ConnectionClass, <src>@<prop>, <dst>@<prop>, ... format.

    connection_loader = ConnectionDataCSV(
        "connections.csv",
        connection_class="HasImage",
        src_class="Person",
        dst_class="Image",
        src_prop_key="name",     # Match the 'name' column in persons to 'src_name'
        src_prop_val="src_name",
        dst_prop_key="url",      # Match the 'url' column in images to 'dst_url'
        dst_prop_val="dst_url",
        connection_property="connection_property"
    )

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

examples/loaders_101/data_loader_hierarchy.py:62

• Similarly, images.csv has no constraint_... columns. Without a uniqueness constraint (e.g., constraint_image_id = image_id), rerunning the example will create duplicate _Image entities, and lookups by image_id in the later connection step will become ambiguous in real scenarios. Consider adding a constraint column to keep the example reproducible/idempotent.

    df_images = pd.DataFrame({
        "filename": [dummy_image_path, dummy_image_path],
        "image_id": ["img1", "img2"],
        "source": ["camera1", "camera2"]
    })
    images_csv = os.path.join(base_dir, "images.csv")
    df_images.to_csv(images_csv, index=False)