.. _auto_ontology_compare:

*ONTOLOGY COMPARE*
==================

Compares two ARC2 ontology stores by executing a shared SPARQL query against each and performing entity-level and property-level diff analysis. Use this worker to detect additions, deletions, and value changes between two versions of a simulation or domain ontology.

When to use
-----------

Tagged: ``arc2``, ``compare``, ``diff``, ``entity-matching``, ``ontology``, ``property-delta``, ``rdf``, ``sparql``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - First Ontology Store Name
     - first_ontology_store_name
     - text
     - —
     - ✓
     - Name of the ARC2 ontology store that acts as the baseline or reference (e.g., 'simulation_v1'); must already be set up before this worker runs.
   * - Second Ontology Store Name
     - second_ontology_store_name
     - text
     - —
     - ✓
     - Name of the ARC2 ontology store to compare against the baseline (e.g., 'simulation_v2'); must already be set up before this worker runs.
   * - SPARQL Query
     - sparql_query
     - text
     - —
     - ✓
     - SPARQL SELECT query executed identically on both stores; projected variables become the columns used for entity matching and property comparison (e.g., SELECT ?nodeId ?mass WHERE { … }).
   * - Comparison Keys
     - comparison_keys
     - string
     - —
     - 
     - Comma-separated list of SPARQL variable names that uniquely identify an entity across stores (e.g., 'nodeId'); leave empty to treat every projected column as part of the key and perform exact row matching.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Status
     - status
     - text
     - Human-readable success or error message describing the outcome of the comparison operation.
   * - First Store Count
     - first_store_count
     - number
     - Total number of result rows returned by the SPARQL query against the first ontology store (integer count).
   * - Second Store Count
     - second_store_count
     - number
     - Total number of result rows returned by the SPARQL query against the second ontology store (integer count).
   * - Only in First Count
     - only_in_first_count
     - number
     - Count of entities whose comparison-key values appear exclusively in the first store (integer; indicates deletions relative to the second store).
   * - Only in Second Count
     - only_in_second_count
     - number
     - Count of entities whose comparison-key values appear exclusively in the second store (integer; indicates additions relative to the first store).
   * - In Both Count
     - in_both_count
     - number
     - Count of entities whose comparison-key values are present in both stores and were therefore eligible for property-level diffing (integer).
   * - Similarity Percentage
     - similarity_percentage
     - number
     - Overlap ratio expressed as a percentage: (entities in both / total unique entities) × 100; ranges from 0 to 100.
   * - Changes Percentage
     - changes_percentage
     - number
     - Proportion of matched entities that have at least one differing property value, expressed as a percentage: (changed entities / entities in both) × 100; ranges from 0 to 100.
   * - Only in First Store
     - only_in_first
     - dataset
     - Dataset containing the full projected rows for entities found exclusively in the first store; column schema mirrors the SPARQL SELECT variables.
   * - Only in Second Store
     - only_in_second
     - dataset
     - Dataset containing the full projected rows for entities found exclusively in the second store; column schema mirrors the SPARQL SELECT variables.
   * - In Both Stores
     - in_both
     - dataset
     - Dataset of full rows (taken from the first store) for entities present in both stores; useful as a reference baseline for the change analysis.
   * - Property Changes
     - changes
     - dataset
     - Dataset with one row per matched entity that has property differences; columns include the comparison-key columns plus, for each non-key property, first_{prop}, second_{prop}, {prop}_changed (boolean), {prop}_delta (numeric difference or null), and {prop}_delta_percentage (relative change or null).

Disciplines
-----------

- platform.ontology

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>ontology_compare</code>. Schema hash: <code>b381f78213e3</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>