Include query plan used to populate cache in REST reply

Summary: This diff adds the plan for the query that is used to populate a query cache to a query_info REST reply. By default the plan of a cached query only shows the instruction that is used to iterate the query cache, but not the instructions that are used to populate the cache, which can make debugging harder. This change is visible in the explorer query inspector (the "Cache plan" is new): {F1907628875} Differential Revision: D63866489
SanderMertens · Oct 3, 2024 · d8ee3ae · d8ee3ae
1 parent 97ee7c6
commit d8ee3ae
Show file tree

Hide file tree

Showing 10 changed files with 228 additions and 34 deletions.
diff --git a/distr/flecs.c b/distr/flecs.c
@@ -32449,6 +32449,17 @@ int32_t ecs_query_match_count(
     }
 }
 
+const ecs_query_t* ecs_query_get_cache_query(
+    const ecs_query_t *q)
+{
+    ecs_query_impl_t *impl = flecs_query_impl(q);
+    if (!impl->cache) {
+        return NULL;
+    } else {
+        return impl->cache->query;
+    }
+}
+
  /**
  * @file query/util.c
  * @brief Query utilities.
@@ -42554,17 +42565,49 @@ void flecs_json_serialize_query_plan(
 
     const ecs_query_t *q = desc->query;
     flecs_poly_assert(q, ecs_query_t);
-
+    const ecs_query_t *cq = ecs_query_get_cache_query(q);
+
     flecs_json_memberl(buf, "query_plan");
 
     bool prev_color = ecs_log_enable_colors(true);
     char *plan = ecs_query_plan(q);
+    char *cache_plan = NULL;
+    if (cq) {
+        flecs_poly_assert(cq, ecs_query_t);
+        cache_plan = ecs_query_plan(cq);
+    }
+
+    ecs_strbuf_t plan_buf = ECS_STRBUF_INIT;
     if (plan) {
-        flecs_json_string_escape(buf, plan);
-        ecs_os_free(plan);
+        ecs_strbuf_appendstr(&plan_buf, plan);
+    } else {
+        if (q->term_count) {
+            ecs_strbuf_append(&plan_buf, "   %sOptimized out (trivial query)\n", ECS_GREY);
+        }
+    }
+
+    if (cq) {
+        ecs_strbuf_appendstr(&plan_buf, "\n\n");
+        ecs_strbuf_appendstr(&plan_buf, "   Cache plan\n");
+        ecs_strbuf_appendstr(&plan_buf, "   ---\n");
+
+        if (cache_plan) {
+            ecs_strbuf_appendstr(&plan_buf, cache_plan);
+        } else {
+            ecs_strbuf_append(&plan_buf, "   %sOptimized out (trivial query)\n", ECS_GREY);
+        }
+    }
+
+    char *plan_str = ecs_strbuf_get(&plan_buf);
+    if (plan_str) {
+        flecs_json_string_escape(buf, plan_str);
+        ecs_os_free(plan_str);
     } else {
         flecs_json_null(buf);
     }
+
+    ecs_os_free(plan);
+    ecs_os_free(cache_plan);
     ecs_log_enable_colors(prev_color);
 }
 

diff --git a/distr/flecs.h b/distr/flecs.h
@@ -8168,6 +8168,18 @@ FLECS_API
 bool ecs_query_is_true(
     const ecs_query_t *query);
 
+/** Get query used to populate cache.
+ * This operation returns the query that is used to populate the query cache.
+ * For queries that are can be entirely cached, the returned query will be 
+ * equivalent to the query passed to ecs_query_get_cache_query().
+ *
+ * @param query The query.
+ * @return The query used to populate the cache, NULL if query is not cached.
+ */
+FLECS_API
+const ecs_query_t* ecs_query_get_cache_query(
+    const ecs_query_t *query);
+
 /** @} */
 
 /**

diff --git a/include/flecs.h b/include/flecs.h
@@ -4951,6 +4951,18 @@ FLECS_API
 bool ecs_query_is_true(
     const ecs_query_t *query);
 
+/** Get query used to populate cache.
+ * This operation returns the query that is used to populate the query cache.
+ * For queries that are can be entirely cached, the returned query will be 
+ * equivalent to the query passed to ecs_query_get_cache_query().
+ *
+ * @param query The query.
+ * @return The query used to populate the cache, NULL if query is not cached.
+ */
+FLECS_API
+const ecs_query_t* ecs_query_get_cache_query(
+    const ecs_query_t *query);
+
 /** @} */
 
 /**

diff --git a/src/addons/json/serialize_iter.c b/src/addons/json/serialize_iter.c
@@ -125,17 +125,49 @@ void flecs_json_serialize_query_plan(
 
     const ecs_query_t *q = desc->query;
     flecs_poly_assert(q, ecs_query_t);
-
+    const ecs_query_t *cq = ecs_query_get_cache_query(q);
+
     flecs_json_memberl(buf, "query_plan");
 
     bool prev_color = ecs_log_enable_colors(true);
     char *plan = ecs_query_plan(q);
+    char *cache_plan = NULL;
+    if (cq) {
+        flecs_poly_assert(cq, ecs_query_t);
+        cache_plan = ecs_query_plan(cq);
+    }
+
+    ecs_strbuf_t plan_buf = ECS_STRBUF_INIT;
     if (plan) {
-        flecs_json_string_escape(buf, plan);
-        ecs_os_free(plan);
+        ecs_strbuf_appendstr(&plan_buf, plan);
+    } else {
+        if (q->term_count) {
+            ecs_strbuf_append(&plan_buf, "   %sOptimized out (trivial query)\n", ECS_GREY);
+        }
+    }
+
+    if (cq) {
+        ecs_strbuf_appendstr(&plan_buf, "\n\n");
+        ecs_strbuf_appendstr(&plan_buf, "   Cache plan\n");
+        ecs_strbuf_appendstr(&plan_buf, "   ---\n");
+
+        if (cache_plan) {
+            ecs_strbuf_appendstr(&plan_buf, cache_plan);
+        } else {
+            ecs_strbuf_append(&plan_buf, "   %sOptimized out (trivial query)\n", ECS_GREY);
+        }
+    }
+
+    char *plan_str = ecs_strbuf_get(&plan_buf);
+    if (plan_str) {
+        flecs_json_string_escape(buf, plan_str);
+        ecs_os_free(plan_str);
     } else {
         flecs_json_null(buf);
     }
+
+    ecs_os_free(plan);
+    ecs_os_free(cache_plan);
     ecs_log_enable_colors(prev_color);
 }
 

diff --git a/src/query/api.c b/src/query/api.c
@@ -509,3 +509,14 @@ int32_t ecs_query_match_count(
         return impl->cache->match_count;
     }
 }
+
+const ecs_query_t* ecs_query_get_cache_query(
+    const ecs_query_t *q)
+{
+    ecs_query_impl_t *impl = flecs_query_impl(q);
+    if (!impl->cache) {
+        return NULL;
+    } else {
+        return impl->cache->query;
+    }
+}
diff --git a/test/meta/src/SerializeQueryInfoToJson.c b/test/meta/src/SerializeQueryInfoToJson.c
@@ -710,7 +710,7 @@ void SerializeQueryInfoToJson_serialize_plan_trivial_query(void) {
     };
 
     char *json = ecs_iter_to_json(&it, &desc);
-    char *expect = flecs_asprintf("{\"query_plan\":null, \"results\":[]}");
+    char *expect = flecs_asprintf("{\"query_plan\":\"   [[0;37mOptimized out (trivial query)\\n\", \"results\":[]}");
     test_json(json, expect);
     ecs_os_free(json);
     ecs_os_free(expect);

diff --git a/test/query/include/query/bake_config.h b/test/query/include/query/bake_config.h
@@ -1,25 +1,25 @@
-/*
-                                   )
-                                  (.)
-                                  .|.
-                                  | |
-                              _.--| |--._
-                           .-';  ;`-'& ; `&.
-                          \   &  ;    &   &_/
-                           |"""---...---"""|
-                           \ | | | | | | | /
-                            `---.|.|.|.---'
-
- * This file is generated by bake.lang.c for your convenience. Headers of
- * dependencies will automatically show up in this file. Include bake_config.h
- * in your main project file. Do not edit! */
-
-#ifndef QUERY_BAKE_CONFIG_H
-#define QUERY_BAKE_CONFIG_H
-
-/* Headers of public dependencies */
-#include <flecs.h>
-#include <bake_test.h>
-
-#endif
-
+/*
+                                   )
+                                  (.)
+                                  .|.
+                                  | |
+                              _.--| |--._
+                           .-';  ;`-'& ; `&.
+                          \   &  ;    &   &_/
+                           |"""---...---"""|
+                           \ | | | | | | | /
+                            `---.|.|.|.---'
+
+ * This file is generated by bake.lang.c for your convenience. Headers of
+ * dependencies will automatically show up in this file. Include bake_config.h
+ * in your main project file. Do not edit! */
+
+#ifndef QUERY_BAKE_CONFIG_H
+#define QUERY_BAKE_CONFIG_H
+
+/* Headers of public dependencies */
+#include <flecs.h>
+#include <bake_test.h>
+
+#endif
+
diff --git a/test/query/project.json b/test/query/project.json
@@ -692,7 +692,10 @@
                 "written_pair_any_any_record",
                 "pair_rel_any_record_component",
                 "pair_tgt_any_record_component",
-                "entity_iteration_w_match_empty_tables"
+                "entity_iteration_w_match_empty_tables",
+                "get_cache_query_uncached",
+                "get_cache_query_cached",
+                "get_cache_query_partially_cached"
             ]
         }, {
             "id": "Combinations",

diff --git a/test/query/src/Basic.c b/test/query/src/Basic.c
@@ -11259,3 +11259,69 @@ void Basic_entity_iteration_w_match_empty_tables(void) {
 
     ecs_fini(world);
 }
+
+void Basic_get_cache_query_uncached(void) {
+    ecs_world_t *world = ecs_mini();
+
+    ECS_COMPONENT(world, Position);
+
+    ecs_query_t *q = ecs_query(world, {
+        .expr = "Position",
+        .cache_kind = EcsQueryCacheNone
+    });
+
+    test_assert(q != NULL);
+
+    const ecs_query_t *cq = ecs_query_get_cache_query(q);
+    test_assert(cq == NULL);
+
+    ecs_query_fini(q);
+
+    ecs_fini(world);
+}
+
+void Basic_get_cache_query_cached(void) {
+    ecs_world_t *world = ecs_mini();
+
+    ECS_COMPONENT(world, Position);
+
+    ecs_query_t *q = ecs_query(world, {
+        .expr = "Position",
+        .cache_kind = EcsQueryCacheAll
+    });
+
+    test_assert(q != NULL);
+
+    const ecs_query_t *cq = ecs_query_get_cache_query(q);
+    test_assert(cq != NULL);
+
+    test_int(cq->term_count, 1);
+    test_int(cq->terms[0].id, ecs_id(Position));
+
+    ecs_query_fini(q);
+
+    ecs_fini(world);
+}
+
+void Basic_get_cache_query_partially_cached(void) {
+    ecs_world_t *world = ecs_mini();
+
+    ECS_COMPONENT(world, Position);
+
+    ecs_query_t *q = ecs_query(world, {
+        .expr = "Position, (ChildOf, $this)", // 2nd term cannot be cached
+        .cache_kind = EcsQueryCacheAuto
+    });
+
+    test_assert(q != NULL);
+
+    const ecs_query_t *cq = ecs_query_get_cache_query(q);
+    test_assert(cq != NULL);
+
+    test_int(cq->term_count, 1);
+    test_int(cq->terms[0].id, ecs_id(Position));
+
+    ecs_query_fini(q);
+
+    ecs_fini(world);
+}
diff --git a/test/query/src/main.c b/test/query/src/main.c
@@ -681,6 +681,9 @@ void Basic_written_pair_any_any_record(void);
 void Basic_pair_rel_any_record_component(void);
 void Basic_pair_tgt_any_record_component(void);
 void Basic_entity_iteration_w_match_empty_tables(void);
+void Basic_get_cache_query_uncached(void);
+void Basic_get_cache_query_cached(void);
+void Basic_get_cache_query_partially_cached(void);
 
 // Testsuite 'Combinations'
 void Combinations_setup(void);
@@ -4782,6 +4785,18 @@ bake_test_case Basic_testcases[] = {
     {
         "entity_iteration_w_match_empty_tables",
         Basic_entity_iteration_w_match_empty_tables
+    },
+    {
+        "get_cache_query_uncached",
+        Basic_get_cache_query_uncached
+    },
+    {
+        "get_cache_query_cached",
+        Basic_get_cache_query_cached
+    },
+    {
+        "get_cache_query_partially_cached",
+        Basic_get_cache_query_partially_cached
     }
 };
 
@@ -10412,7 +10427,7 @@ static bake_test_suite suites[] = {
         "Basic",
         Basic_setup,
         NULL,
-        225,
+        228,
         Basic_testcases,
         1,
         Basic_params