ProfiledPlan: expose existence for all metrics (#687)

* Move internal summary types and values into internal package

* ProfiledPlan: expose existence for all metrics

* Use `(T, bool)` instead of `hasXyz` methods.

* Rename interface `Profile` to `QueryProfile`

* Rename `idb.Summary`'s `ProfiledPlan` to `Profile`

* Make `QueryProfile.Time()` return `time.Duration` instead of int64

---------

Co-authored-by: Stephen Cathcart <stephen.cathcart@neo4j.com>

Author: robsdedude

neo4j/db/summary.go

@@ -19,35 +19,47 @@ package db
 
 // Definitions of these should correspond to public API
 //
-// Deprecated: Use QueryType instead. This will be removed in a future release.
+// Deprecated: Use neo4j.QueryType instead. This will be removed in a future release.
 type StatementType int
 
 const (
-	// Deprecated: Use QueryTypeUnknown instead. This will be removed in a future release.
+	// Deprecated: Use neo4j.QueryTypeUnknown instead. This will be removed in a future release.
 	StatementTypeUnknown StatementType = 0
-	// Deprecated: Use QueryTypeRead instead. This will be removed in a future release.
+	// Deprecated: Use neo4j.QueryTypeReadOnly instead. This will be removed in a future release.
 	StatementTypeRead StatementType = 1
-	// Deprecated: Use QueryTypeReadWrite instead. This will be removed in a future release.
+	// Deprecated: Use neo4j.QueryTypeReadWrite instead. This will be removed in a future release.
 	StatementTypeReadWrite StatementType = 2
-	// Deprecated: Use QueryTypeWrite instead. This will be removed in a future release.
+	// Deprecated: Use neo4j.QueryTypeWriteOnly instead. This will be removed in a future release.
 	StatementTypeWrite StatementType = 3
-	// Deprecated: Use QueryTypeSchemaWrite instead. This will be removed in a future release.
+	// Deprecated: Use neo4j.QueryTypeSchemaWrite instead. This will be removed in a future release.
 	StatementTypeSchemaWrite StatementType = 4
 )
 
 // QueryType defines the type of the query
+//
+// Deprecated: Use neo4j.QueryType instead. This will be removed in a future release.
 type QueryType = StatementType
 
 const (
 	// QueryTypeUnknown identifies an unknown query type
+	//
+	// Deprecated: Use neo4j.QueryTypeUnknown instead. This will be removed in a future release.
 	QueryTypeUnknown QueryType = 0
 	// QueryTypeRead identifies a read query
+	//
+	// Deprecated: Use neo4j.QueryTypeReadOnly instead. This will be removed in a future release.
 	QueryTypeRead QueryType = 1
 	// QueryTypeReadWrite identifies a read-write query
+	//
+	// Deprecated: Use neo4j.QueryTypeReadWrite instead. This will be removed in a future release.
 	QueryTypeReadWrite QueryType = 2
 	// QueryTypeWrite identifies a write query
+	//
+	// Deprecated: Use neo4j.QueryTypeWriteOnly instead. This will be removed in a future release.
 	QueryTypeWrite QueryType = 3
 	// QueryTypeSchemaWrite identifies a schema-write query
+	//
+	// Deprecated: Use neo4j.QueryTypeSchemaWrite instead. This will be removed in a future release.
 	QueryTypeSchemaWrite QueryType = 4
 )
 
@@ -73,6 +85,8 @@ const (
 // plans. The statement starts with the root plan. Each sub-plan is of a specific operator, which describes what
 // that part of the plan does - for instance, perform an index lookup or filter results.
 // The Neo4j Manual contains a reference of the available operator types, and these may differ across Neo4j versions.
+//
+// Deprecated: Internal type. This will be removed in a future release.
 type Plan struct {
 	// Operator is the operation this plan is performing.
 	Operator string
@@ -90,6 +104,8 @@ type Plan struct {
 
 // ProfiledPlan is the same as a regular 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.
+//
+// Deprecated: Internal type. This will be removed in a future release.
 type ProfiledPlan struct {
 	// Operator contains the operation this plan is performing.
 	Operator string
@@ -113,6 +129,7 @@ type ProfiledPlan struct {
 	Time              int64
 }
 
+// Deprecated: Internal type. This will be removed in a future release.
 type StreamSummary struct {
 	HadRecord bool
 	HadKey    bool
@@ -131,6 +148,8 @@ type Notification struct {
 // GqlStatusObject represents a GqlStatusObject generated when executing a statement.
 // A GqlStatusObject can be visualized in a client pinpointing problems or other information about the statement.
 // Contrary to failures or errors, GqlStatusObjects do not affect the execution of the statement.
+//
+// Deprecated: Internal type. This will be removed in a future release.
 type GqlStatusObject struct {
 	// Deprecated: for backward compatibility with Notification.Code only.
 	Code string
@@ -175,6 +194,8 @@ type GqlStatusObject struct {
 }
 
 // InputPosition contains information about a specific position in a statement
+//
+// Deprecated: Internal type. This will be removed in a future release.
 type InputPosition struct {
 	// Offset contains the character offset referred to by this position; offset numbers start at 0.
 	Offset int
@@ -189,6 +210,7 @@ type ProtocolVersion struct {
 	Minor int
 }
 
+// Deprecated: Internal type. This will be removed in a future release.
 type Summary struct {
 	Bookmark              string
 	StmntType             StatementType

neo4j/driver.go

@@ -527,7 +527,7 @@ func (d *driver) VerifyAuthentication(ctx context.Context, auth *AuthToken) (err
 //		summary, _ := result.Consume(ctx)
 //		return &neo4j.EagerResult{
 //			Keys:    keys,
-//			Records: records,
+//			Rows: records,
 //			Summary: summary,
 //		}, nil
 //	})

neo4j/driver_test.go

@@ -967,6 +967,10 @@ func (sum *fakeSummary) Profile() ProfiledPlan {
 	panic("implement me")
 }
 
+func (sum *fakeSummary) QueryProfile() QueryProfile {
+	panic("implement me")
+}
+
 func (sum *fakeSummary) Notifications() []Notification {
 	panic("implement me")
 }

neo4j/internal/bolt/bolt3.go

@@ -424,7 +424,7 @@ func (b *bolt3) discardStream(ctx context.Context) error {
 	}
 
 	var (
-		sum *db.Summary
+		sum *idb.Summary
 		err error
 	)
 	for sum == nil && err == nil {
@@ -442,7 +442,7 @@ func (b *bolt3) bufferStream(ctx context.Context) error {
 
 	n := 0
 	var (
-		sum *db.Summary
+		sum *idb.Summary
 		err error
 		rec *db.Record
 	)
@@ -552,7 +552,7 @@ func (b *bolt3) Keys(streamHandle idb.StreamHandle) ([]string, error) {
 
 // Reads one record from the stream.
 func (b *bolt3) Next(ctx context.Context, streamHandle idb.StreamHandle) (
-	*db.Record, *db.Summary, error) {
+	*db.Record, *idb.Summary, error) {
 	stream, ok := streamHandle.(*stream)
 	if !ok {
 		return nil, nil, errors.New("invalid stream handle")
@@ -574,7 +574,7 @@ func (b *bolt3) Next(ctx context.Context, streamHandle idb.StreamHandle) (
 }
 
 func (b *bolt3) Consume(ctx context.Context, streamHandle idb.StreamHandle) (
-	*db.Summary, error) {
+	*idb.Summary, error) {
 	stream, ok := streamHandle.(*stream)
 	if !ok {
 		return nil, errors.New("invalid stream handle")
@@ -618,7 +618,7 @@ func (b *bolt3) Buffer(ctx context.Context,
 }
 
 // Reads one record from the network.
-func (b *bolt3) receiveNext(ctx context.Context) (*db.Record, *db.Summary, error) {
+func (b *bolt3) receiveNext(ctx context.Context) (*db.Record, *idb.Summary, error) {
 	if err := b.assertState(bolt3_streaming, bolt3_streamingtx); err != nil {
 		return nil, nil, err
 	}
@@ -859,8 +859,8 @@ func (b *bolt3) ReAuth(ctx context.Context, auth *idb.ReAuthToken) error {
 	return nil
 }
 
-func (b *bolt3) Version() db.ProtocolVersion {
-	return db.ProtocolVersion{
+func (b *bolt3) Version() idb.ProtocolVersion {
+	return idb.ProtocolVersion{
 		Major: 3,
 		Minor: b.minor,
 	}

neo4j/internal/bolt/bolt4.go

@@ -666,7 +666,7 @@ func (b *bolt4) Keys(streamHandle idb.StreamHandle) ([]string, error) {
 
 // Next reads one record from the stream.
 func (b *bolt4) Next(ctx context.Context, streamHandle idb.StreamHandle) (
-	*db.Record, *db.Summary, error) {
+	*db.Record, *idb.Summary, error) {
 	// Do NOT set b.err for this error
 	stream, err := b.streams.getUnsafe(streamHandle)
 	if err != nil {
@@ -699,7 +699,7 @@ func (b *bolt4) Next(ctx context.Context, streamHandle idb.StreamHandle) (
 }
 
 func (b *bolt4) Consume(ctx context.Context, streamHandle idb.StreamHandle) (
-	*db.Summary, error) {
+	*idb.Summary, error) {
 	// Do NOT set b.err for this error
 	stream, err := b.streams.getUnsafe(streamHandle)
 	if err != nil {
@@ -972,8 +972,8 @@ func (b *bolt4) ReAuth(ctx context.Context, auth *idb.ReAuthToken) error {
 	return nil
 }
 
-func (b *bolt4) Version() db.ProtocolVersion {
-	return db.ProtocolVersion{
+func (b *bolt4) Version() idb.ProtocolVersion {
+	return idb.ProtocolVersion{
 		Major: 4,
 		Minor: b.minor,
 	}
@@ -1193,7 +1193,7 @@ func (b *bolt4) initializeReadTimeoutHint(hints map[string]any) {
 	b.queue.in.connReadTimeout = time.Duration(readTimeout) * time.Second
 }
 
-func (b *bolt4) extractSummary(success *success, stream *stream) *db.Summary {
+func (b *bolt4) extractSummary(success *success, stream *stream) *idb.Summary {
 	summary := success.summary()
 	summary.Agent = b.serverVersion
 	summary.Major = 4

neo4j/internal/bolt/bolt5.go

@@ -65,7 +65,7 @@ type internalTx5 struct {
 	notificationConfig idb.NotificationConfig
 }
 
-func (i *internalTx5) toMeta(logger log.Logger, logId string, version db.ProtocolVersion) map[string]any {
+func (i *internalTx5) toMeta(logger log.Logger, logId string, version idb.ProtocolVersion) map[string]any {
 	if i == nil {
 		return nil
 	}
@@ -662,7 +662,7 @@ func (b *bolt5) Keys(streamHandle idb.StreamHandle) ([]string, error) {
 
 // Next reads one record from the stream.
 func (b *bolt5) Next(ctx context.Context, streamHandle idb.StreamHandle) (
-	*db.Record, *db.Summary, error) {
+	*db.Record, *idb.Summary, error) {
 	// Do NOT set b.err for this error
 	stream, err := b.streams.getUnsafe(streamHandle)
 	if err != nil {
@@ -695,7 +695,7 @@ func (b *bolt5) Next(ctx context.Context, streamHandle idb.StreamHandle) (
 }
 
 func (b *bolt5) Consume(ctx context.Context, streamHandle idb.StreamHandle) (
-	*db.Summary, error) {
+	*idb.Summary, error) {
 	// Do NOT set b.err for this error
 	stream, err := b.streams.getUnsafe(streamHandle)
 	if err != nil {
@@ -964,8 +964,8 @@ func (b *bolt5) Database() string {
 	return b.databaseName
 }
 
-func (b *bolt5) Version() db.ProtocolVersion {
-	return db.ProtocolVersion{
+func (b *bolt5) Version() idb.ProtocolVersion {
+	return idb.ProtocolVersion{
 		Major: 5,
 		Minor: b.minor,
 	}
@@ -1232,7 +1232,7 @@ func (b *bolt5) initializeSsrEnabledHint(hints map[string]any) {
 	b.ssrEnabled = ssrEnabled
 }
 
-func (b *bolt5) extractSummary(success *success, stream *stream) *db.Summary {
+func (b *bolt5) extractSummary(success *success, stream *stream) *idb.Summary {
 	summary := success.summary()
 	summary.Agent = b.serverVersion
 	summary.Major = 5

neo4j/internal/bolt/bolt5_test.go

@@ -1939,7 +1939,7 @@ func TestBolt5(outer *testing.T) {
 	for _, test := range txTimeoutTestCases {
 		outer.Run(test.description, func(t *testing.T) {
 			tx := internalTx5{timeout: test.input}
-			version := db.ProtocolVersion{Major: 5, Minor: 0}
+			version := idb.ProtocolVersion{Major: 5, Minor: 0}
 			actual, ok := tx.toMeta(logger, "", version)["tx_timeout"]
 			if test.omitted {
 				if ok {

neo4j/internal/bolt/bolt6.go

@@ -60,7 +60,7 @@ type internalTx6 struct {
 	notificationConfig idb.NotificationConfig
 }
 
-func (i *internalTx6) toMeta(logger log.Logger, logId string, version db.ProtocolVersion) map[string]any {
+func (i *internalTx6) toMeta(logger log.Logger, logId string, version idb.ProtocolVersion) map[string]any {
 	if i == nil {
 		return nil
 	}
@@ -658,7 +658,7 @@ func (b *bolt6) Keys(streamHandle idb.StreamHandle) ([]string, error) {
 
 // Next reads one record from the stream.
 func (b *bolt6) Next(ctx context.Context, streamHandle idb.StreamHandle) (
-	*db.Record, *db.Summary, error) {
+	*db.Record, *idb.Summary, error) {
 	// Do NOT set b.err for this error
 	stream, err := b.streams.getUnsafe(streamHandle)
 	if err != nil {
@@ -691,7 +691,7 @@ func (b *bolt6) Next(ctx context.Context, streamHandle idb.StreamHandle) (
 }
 
 func (b *bolt6) Consume(ctx context.Context, streamHandle idb.StreamHandle) (
-	*db.Summary, error) {
+	*idb.Summary, error) {
 	// Do NOT set b.err for this error
 	stream, err := b.streams.getUnsafe(streamHandle)
 	if err != nil {
@@ -933,8 +933,8 @@ func (b *bolt6) Database() string {
 	return b.databaseName
 }
 
-func (b *bolt6) Version() db.ProtocolVersion {
-	return db.ProtocolVersion{
+func (b *bolt6) Version() idb.ProtocolVersion {
+	return idb.ProtocolVersion{
 		Major: 6,
 		Minor: b.minor,
 	}
@@ -1201,7 +1201,7 @@ func (b *bolt6) initializeSsrEnabledHint(hints map[string]any) {
 	b.ssrEnabled = ssrEnabled
 }
 
-func (b *bolt6) extractSummary(success *success, stream *stream) *db.Summary {
+func (b *bolt6) extractSummary(success *success, stream *stream) *idb.Summary {
 	summary := success.summary()
 	summary.Agent = b.serverVersion
 	summary.Major = 6

neo4j/internal/bolt/bolt6_test.go

@@ -1718,7 +1718,7 @@ func TestBolt6(outer *testing.T) {
 	for _, test := range txTimeoutTestCases {
 		outer.Run(test.description, func(t *testing.T) {
 			tx := internalTx6{timeout: test.input}
-			version := db.ProtocolVersion{Major: 6, Minor: 0}
+			version := idb.ProtocolVersion{Major: 6, Minor: 0}
 			actual, ok := tx.toMeta(logger, "", version)["tx_timeout"]
 			if test.omitted {
 				if ok {