ProfiledPlan: expose existence for all metrics

driver/clirr-ignored-differences.xml

@@ -953,4 +953,10 @@
         <method>org.neo4j.driver.types.Vector asVector()</method>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/summary/ResultSummary</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.summary.Profile queryProfile()</method>
+    </difference>
+
 </differences>

driver/src/main/java/org/neo4j/driver/internal/summary/InternalProfile.java

@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.neo4j.driver.internal.summary;
+
+import java.util.List;
+import java.util.Map;
+import java.util.OptionalDouble;
+import java.util.OptionalLong;
+import java.util.function.Function;
+import org.neo4j.driver.Value;
+import org.neo4j.driver.summary.Profile;
+
+public class InternalProfile extends InternalPlan<Profile> implements Profile {
+
+    private final OptionalLong dbHits;
+    private final OptionalLong rows;
+    private final OptionalLong pageCacheHits;
+    private final OptionalLong pageCacheMisses;
+    private final OptionalDouble pageCacheHitRatio;
+    private final OptionalLong time;
+
+    protected InternalProfile(
+            String operatorType,
+            Map<String, Value> arguments,
+            List<String> identifiers,
+            List<Profile> children,
+            OptionalLong dbHits,
+            OptionalLong rows,
+            OptionalLong pageCacheHits,
+            OptionalLong pageCacheMisses,
+            OptionalDouble pageCacheHitRatio,
+            OptionalLong time) {
+        super(operatorType, arguments, identifiers, children);
+        this.dbHits = dbHits;
+        this.rows = rows;
+        this.pageCacheHits = pageCacheHits;
+        this.pageCacheMisses = pageCacheMisses;
+        this.pageCacheHitRatio = pageCacheHitRatio;
+        this.time = time;
+    }
+
+    @Override
+    public OptionalLong dbHits() {
+        return dbHits;
+    }
+
+    @Override
+    public OptionalLong rows() {
+        return rows;
+    }
+
+    @Override
+    public OptionalLong pageCacheHits() {
+        return pageCacheHits;
+    }
+
+    @Override
+    public OptionalLong pageCacheMisses() {
+        return pageCacheMisses;
+    }
+
+    @Override
+    public OptionalDouble pageCacheHitRatio() {
+        return pageCacheHitRatio;
+    }
+
+    @Override
+    public OptionalLong time() {
+        return time;
+    }
+
+    private static final PlanCreator<Profile> PROFILE =
+            (operatorType, arguments, identifiers, children, originalPlanValue) -> new InternalProfile(
+                    operatorType,
+                    arguments,
+                    identifiers,
+                    children,
+                    originalPlanValue
+                            .get("dbHits")
+                            .computeOrDefault(v -> OptionalLong.of(v.asLong()), OptionalLong.empty()),
+                    originalPlanValue
+                            .get("rows")
+                            .computeOrDefault(v -> OptionalLong.of(v.asLong()), OptionalLong.empty()),
+                    originalPlanValue
+                            .get("pageCacheHits")
+                            .computeOrDefault(v -> OptionalLong.of(v.asLong()), OptionalLong.empty()),
+                    originalPlanValue
+                            .get("pageCacheMisses")
+                            .computeOrDefault(v -> OptionalLong.of(v.asLong()), OptionalLong.empty()),
+                    originalPlanValue
+                            .get("pageCacheHitRatio")
+                            .computeOrDefault(v -> OptionalDouble.of(v.asDouble()), OptionalDouble.empty()),
+                    originalPlanValue
+                            .get("time")
+                            .computeOrDefault(v -> OptionalLong.of(v.asLong()), OptionalLong.empty()));
+
+    /**
+     * Builds a regular plan without profiling information - eg. a plan that came as a result of an `EXPLAIN` query
+     */
+    public static final Function<Value, Profile> PROFILE_FROM_VALUE = new Converter<>(PROFILE);
+}

driver/src/main/java/org/neo4j/driver/internal/summary/InternalProfiledPlan.java

@@ -22,6 +22,7 @@
 import org.neo4j.driver.Value;
 import org.neo4j.driver.summary.ProfiledPlan;
 
+@SuppressWarnings("deprecation")
 public class InternalProfiledPlan extends InternalPlan<ProfiledPlan> implements ProfiledPlan {
     private final long dbHits;
     private final long records;

driver/src/main/java/org/neo4j/driver/internal/summary/InternalResultSummary.java

@@ -25,6 +25,7 @@
 import org.neo4j.driver.summary.GqlStatusObject;
 import org.neo4j.driver.summary.Notification;
 import org.neo4j.driver.summary.Plan;
+import org.neo4j.driver.summary.Profile;
 import org.neo4j.driver.summary.ProfiledPlan;
 import org.neo4j.driver.summary.QueryType;
 import org.neo4j.driver.summary.ResultSummary;
@@ -37,7 +38,11 @@ public class InternalResultSummary implements ResultSummary {
     private final QueryType queryType;
     private final SummaryCounters counters;
     private final Plan plan;
-    private final ProfiledPlan profile;
+
+    @SuppressWarnings("deprecation")
+    private final ProfiledPlan profiledPlan;
+
+    private final Profile profile;
 
     @SuppressWarnings("deprecation")
     private final List<Notification> notifications;
@@ -54,7 +59,8 @@ public InternalResultSummary(
             QueryType queryType,
             SummaryCounters counters,
             Plan plan,
-            ProfiledPlan profile,
+            @SuppressWarnings("deprecation") ProfiledPlan profiledPlan,
+            Profile profile,
             @SuppressWarnings("deprecation") List<Notification> notifications,
             Set<GqlStatusObject> gqlStatusObjects,
             long resultAvailableAfter,
@@ -65,6 +71,7 @@ public InternalResultSummary(
         this.queryType = queryType;
         this.counters = counters;
         this.plan = resolvePlan(plan, profile);
+        this.profiledPlan = profiledPlan;
         this.profile = profile;
         this.notifications = Objects.requireNonNull(notifications);
         this.gqlStatusObjects = Objects.requireNonNull(gqlStatusObjects);
@@ -103,7 +110,13 @@ public Plan plan() {
     }
 
     @Override
+    @SuppressWarnings("deprecation")
     public ProfiledPlan profile() {
+        return profiledPlan;
+    }
+
+    @Override
+    public Profile queryProfile() {
         return profile;
     }
 
@@ -170,7 +183,7 @@ public int hashCode() {
                 queryType,
                 counters,
                 plan,
-                profile,
+                profiledPlan,
                 gqlStatusObjects,
                 resultAvailableAfter,
                 resultConsumedAfter);
@@ -184,7 +197,7 @@ public String toString() {
                 + databaseInfo + ", queryType="
                 + queryType + ", counters="
                 + counters + ", plan="
-                + plan + ", profile="
+                + plan + ", queryProfile="
                 + profile + ", gqlStatusObjects="
                 + gqlStatusObjects + ", resultAvailableAfter="
                 + resultAvailableAfter + ", resultConsumedAfter="
@@ -195,10 +208,10 @@ public String toString() {
      * Profiled plan is a superset of plan. This method returns profiled plan if plan is {@code null}.
      *
      * @param plan the given plan, possibly {@code null}.
-     * @param profiledPlan the given profiled plan, possibly {@code null}.
+     * @param profile the given plan, possibly {@code null}.
      * @return available plan.
      */
-    private static Plan resolvePlan(Plan plan, ProfiledPlan profiledPlan) {
-        return plan == null ? profiledPlan : plan;
+    private static Plan resolvePlan(Plan plan, Profile profile) {
+        return plan == null ? profile : plan;
     }
 }

driver/src/main/java/org/neo4j/driver/internal/util/MetadataExtractor.java

@@ -53,6 +53,7 @@
 import org.neo4j.driver.internal.summary.InternalInputPosition;
 import org.neo4j.driver.internal.summary.InternalNotification;
 import org.neo4j.driver.internal.summary.InternalPlan;
+import org.neo4j.driver.internal.summary.InternalProfile;
 import org.neo4j.driver.internal.summary.InternalProfiledPlan;
 import org.neo4j.driver.internal.summary.InternalResultSummary;
 import org.neo4j.driver.internal.summary.InternalServerInfo;
@@ -62,6 +63,7 @@
 import org.neo4j.driver.summary.InputPosition;
 import org.neo4j.driver.summary.Notification;
 import org.neo4j.driver.summary.Plan;
+import org.neo4j.driver.summary.Profile;
 import org.neo4j.driver.summary.ProfiledPlan;
 import org.neo4j.driver.summary.QueryType;
 import org.neo4j.driver.summary.ResultSummary;
@@ -150,6 +152,7 @@ public ResultSummary extractSummary(
                 extractCounters(metadata),
                 extractPlan(metadata),
                 extractProfiledPlan(metadata),
+                extractProfile(metadata),
                 notifications,
                 gqlStatusObjects,
                 resultAvailableAfter,
@@ -206,6 +209,7 @@ private static Plan extractPlan(Map<String, Value> metadata) {
         return null;
     }
 
+    @SuppressWarnings("deprecation")
     private static ProfiledPlan extractProfiledPlan(Map<String, Value> metadata) {
         var profiledPlanValue = metadata.get("profile");
         if (profiledPlanValue != null) {
@@ -214,6 +218,14 @@ private static ProfiledPlan extractProfiledPlan(Map<String, Value> metadata) {
         return null;
     }
 
+    private static Profile extractProfile(Map<String, Value> metadata) {
+        var profileValue = metadata.get("profile");
+        if (profileValue != null) {
+            return InternalProfile.PROFILE_FROM_VALUE.apply(profileValue);
+        }
+        return null;
+    }
+
     private static Stream<GqlStatusObjectAndNotification> generateGqlStatusObjectsAndExtractNotifications(
             Map<String, Value> metadata) {
         var notificationsValue = metadata.get("notifications");

driver/src/main/java/org/neo4j/driver/summary/Profile.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.neo4j.driver.summary;
+
+import java.util.List;
+import java.util.OptionalDouble;
+import java.util.OptionalLong;
+
+/**
+ * This is the same as a regular {@link Plan} - except this plan has been executed, meaning it also contains detailed information about how much work each
+ * step of the plan incurred on the database.
+ * @since 6.1
+ */
+public interface Profile extends Plan {
+
+    /**
+     * Returns the number of times this part of the plan touched the underlying data stores if it was recorded.
+     *
+     * @return the number of times this part of the plan touched the underlying data stores if it was recorded
+     */
+    OptionalLong dbHits();
+
+    /**
+     * Returns the number of rows processed by the associated execution step if it was recorded.
+     *
+     * @return the number of rows processed by the associated execution step if it was recorded
+     */
+    OptionalLong rows();
+
+    /**
+     * Returns the number of page cache hits caused by executing the associated execution step if it was recorded.
+     *
+     * @return the number of page cache hits caused by executing the associated execution step if it was recorded
+     */
+    OptionalLong pageCacheHits();
+
+    /**
+     * Returns the number of page cache misses caused by executing the associated execution step if it was recorded.
+     *
+     * @return the number of page cache misses caused by executing the associated execution step if it was recorded
+     */
+    OptionalLong pageCacheMisses();
+
+    /**
+     * Returns the ratio of page cache hits to total number of lookups or 0 if no data is available.
+     *
+     * @return the ratio of page cache hits to total number of lookups or 0 if no data is available
+     */
+    OptionalDouble pageCacheHitRatio();
+
+    /**
+     * Returns the amount of time spent in the associated execution step if it was recorded.
+     *
+     * @return the amount of time spent in the associated execution step if it was recorded
+     */
+    OptionalLong time();
+
+    @Override
+    List<? extends Profile> children();
+}

driver/src/main/java/org/neo4j/driver/summary/ProfiledPlan.java

@@ -22,7 +22,9 @@
  * This is the same as a regular {@link Plan} - except this plan has been executed, meaning it also contains detailed information about how much work each
  * step of the plan incurred on the database.
  * @since 1.0
+ * @deprecated superseded by {@link Profile}.
  */
+@Deprecated
 public interface ProfiledPlan extends Plan {
     /**
      * Returns the number of times this part of the plan touched the underlying data stores.
@@ -74,5 +76,5 @@ public interface ProfiledPlan extends Plan {
     long time();
 
     @Override
-    List<ProfiledPlan> children();
+    List<? extends ProfiledPlan> children();
 }

driver/src/main/java/org/neo4j/driver/summary/ResultSummary.java

@@ -85,9 +85,22 @@ public interface ResultSummary {
      * available here.
      *
      * @return profiled query plan for the executed query if available, otherwise null
+     * @deprecated superseded by {@link ResultSummary#queryProfile()}
      */
+    @Deprecated
     ProfiledPlan profile();
 
+    /**
+     * This describes how the database did execute your query.
+     * <p>
+     * If the query you executed {@link #hasProfile() was profiled}, the query plan will contain detailed
+     * information about what each step of the plan did. That more in-depth version of the query plan becomes
+     * available here.
+     *
+     * @return profiled query plan for the executed query if available, otherwise null
+     */
+    Profile queryProfile();
+
     /**
      * A list of notifications that might arise when executing the query.
      * Notifications can be warnings about problematic queries or other valuable information that can be presented