Skip to content

chore: migrate all queries and add_entity calls to use with! syntax.#856

Open
RobertJacobsonCDC wants to merge 5 commits intoRobertJacobsonCDC_814_hash_for_propertyfrom
RobertJacobsonCDC_798_remove_tuple_queries
Open

chore: migrate all queries and add_entity calls to use with! syntax.#856
RobertJacobsonCDC wants to merge 5 commits intoRobertJacobsonCDC_814_hash_for_propertyfrom
RobertJacobsonCDC_798_remove_tuple_queries

Conversation

@RobertJacobsonCDC
Copy link
Copy Markdown
Collaborator

@RobertJacobsonCDC RobertJacobsonCDC commented Apr 25, 2026

This PR removes support for passing naked tuples of property values to the public query and add_entity APIs. Users now express property bundles with with!(Entity, ...), and use the entity type itself, such as Person, when they want the whole population or default initialization.

The query implementation keeps the tuple machinery internally, but the public API is narrowed through a new Query marker trait. The old Query trait was renamed to QueryInternal, its unnecessary Copy bound was removed, and public query methods now accept only the public Query surface. EntityPropertyTuple<E, Q> and entity ZSTs implement that marker; naked tuples do not.

Entity initialization follows the same public-facing rule. add_entity now accepts PropertyInitializationList<E>, which is implemented for with!(Entity, ...) bundles and for the entity type itself. The existing PropertyList<E> tuple machinery remains available for internal initialization work and type-level property lists used by value-change counting.

The branch also migrates examples, tests, benches, and docs away from naked tuple values. User-facing documentation now consistently shows with!(Person, Age(25)) for property-filtered queries or initialization, and Person for whole-population queries or default initialization.

Commits on this PR:

  1. Migrate existing code to the new with!(Entity, ...) style before changing trait bounds, so call-site churn is isolated from API narrowing.
  2. Rename the old Query trait to QueryInternal and remove its unnecessary Copy bound.
  3. Introduce the new public Query marker trait and narrow public query APIs so with!(Entity, ...) and Entity work, but naked tuples do not.
  4. Introduce PropertyInitializationList and narrow add_entity so initialization follows the same public rule: with!(Entity, ...) for property values, Entity for defaults.
  5. Update user-facing docs to explain the new with! and entity-type syntax without exposing the internal trait split.

This PR is stacked on top of #848 and supersedes #833.

@github-actions
Copy link
Copy Markdown

Benchmark Results

Hyperfine

Command Mean [ms] Min [ms] Max [ms] Relative
large_sir::baseline 2.4 ± 0.2 2.3 3.3 1.00
large_sir::entities 4.8 ± 0.3 4.6 6.2 2.01 ± 0.19

Criterion

Regressions (slower)
Group Bench Param Change CI Lower CI Upper
indexing with_query_results_single_indexed_property_entities 28.517% 27.869% 29.216%
counts reindex_after_adding_more_entities 9.296% 9.037% 9.544%
indexing query_people_count_multiple_individually_indexed_properties_enti 7.783% 7.529% 8.194%
indexing with_query_results_indexed_multi-property_entities 7.559% 7.060% 7.915%
sampling sampling_single_l_reservoir_entities 7.415% 7.287% 7.568%
counts single_property_indexed_entities 6.630% 6.188% 7.135%
indexing with_query_results_multiple_individually_indexed_properties_enti 4.826% 4.630% 5.002%
sample_entity sample_entity_whole_population 1000 4.790% 3.608% 6.159%
sampling sampling_multiple_known_length_entities 4.117% 3.674% 4.762%
sample_entity sample_entity_whole_population 10000 3.924% 2.904% 4.991%
counts concrete_plus_derived_unindexed_entities 2.228% 1.717% 2.799%
indexing query_people_count_indexed_multi-property_entities 2.041% 1.266% 2.578%
counts index_after_adding_entities 1.945% 1.572% 2.319%
indexing query_people_multiple_individually_indexed_properties_entities 1.727% 1.511% 1.921%
algorithm_benches algorithm_sampling_multiple_l_reservoir 1.311% 1.039% 1.581%
Improvements (faster)
Group Bench Param Change CI Lower CI Upper
sampling count_and_sampling_single_known_length_entities -12.876% -13.038% -12.693%
large_dataset bench_query_population_multi_unindexed_entities -10.088% -11.783% -8.539%
indexing query_people_single_indexed_property_entities -9.596% -10.814% -8.308%
counts multi_property_indexed_entities -9.435% -9.736% -9.111%
examples example-basic-infection -9.387% -9.862% -9.003%
indexing query_people_indexed_multi-property_entities -7.789% -9.400% -6.093%
sample_entity sample_entity_single_property_unindexed 100000 -7.059% -7.392% -6.750%
sample_entity sample_entity_single_property_indexed 10000 -6.623% -6.894% -6.167%
sample_entity sample_entity_single_property_indexed 1000 -6.300% -6.679% -5.916%
examples example-births-deaths -4.368% -4.789% -4.004%
large_dataset bench_match_entity -3.328% -3.884% -2.881%
sampling sampling_single_known_length_entities -3.245% -3.639% -2.924%
indexing query_people_count_single_indexed_property_entities -3.046% -3.582% -2.405%
large_dataset bench_query_population_indexed_property_entities -2.673% -3.285% -2.192%
sample_entity sample_entity_multi_property_indexed 10000 -2.458% -2.822% -2.064%
sample_entity sample_entity_single_property_indexed 100000 -2.434% -2.790% -2.161%
large_dataset bench_query_population_derived_property_entities -2.355% -3.248% -1.559%
sample_entity sample_entity_multi_property_indexed 1000 -2.208% -2.786% -1.643%
counts multi_property_unindexed_entities -1.653% -2.324% -1.148%
Unchanged / inconclusive (CI crosses 0%)
Group Bench Param Change CI Lower CI Upper
counts single_property_unindexed_entities 1.723% 0.370% 3.248%
large_dataset bench_query_population_property_entities -1.455% -2.874% -0.235%
sampling sampling_single_unindexed_concrete_plus_derived_entities -1.249% -1.590% -0.882%
algorithm_benches algorithm_sampling_multiple_known_length 1.179% -0.315% 2.170%
large_dataset bench_filter_indexed_entity -1.074% -13.070% 12.550%
sample_entity sample_entity_multi_property_indexed 100000 -1.013% -1.971% 0.617%
sampling sampling_multiple_l_reservoir_entities 0.868% 0.797% 0.941%
large_dataset bench_query_population_multi_indexed_entities 0.790% 0.414% 1.211%
sample_entity sample_entity_single_property_unindexed 10000 0.690% 0.335% 1.232%
sample_entity sample_entity_whole_population 100000 -0.542% -3.613% 2.061%
sample_entity sample_entity_single_property_unindexed 1000 -0.465% -0.938% -0.044%
algorithm_benches algorithm_sampling_single_known_length -0.447% -1.042% 0.075%
sampling count_and_sampling_single_unindexed_concrete_plus_derived_entiti 0.416% 0.370% 0.465%
large_dataset bench_filter_unindexed_entity -0.393% -4.928% 4.369%
algorithm_benches algorithm_sampling_single_l_reservoir -0.144% -0.437% 0.067%
sampling sampling_multiple_unindexed_entities -0.114% -0.579% 0.324%
sampling sampling_single_unindexed_entities -0.096% -0.240% 0.020%
algorithm_benches algorithm_sampling_single_rand_reservoir 0.011% -0.115% 0.167%

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant