diff --git a/doc.go b/doc.go index 9ee3974..1fc0c4d 100644 --- a/doc.go +++ b/doc.go @@ -1,65 +1,4 @@ -/*Package goBolt implements a internalDriver for the Neo4J Bolt Protocol. - -The internalDriver is compatible with Golang's sql.internalDriver interface, but -aims to implement a more complete featureset in line with what -Neo4J and Bolt provides. - -As such, there are multiple interfaces the user can choose from. -It's highly recommended that the user use the Neo4J-specific -interfaces as they are more flexible and efficient than the -provided sql.internalDriver compatible methods. - -The interface tries to be consistent throughout. The sql.internalDriver -interfaces are standard, but the Neo4J-specific ones contain a -naming convention of either "Neo" or "Pipeline". - -The "Neo" ones are the basic interfaces for making queries to -Neo4j and it's expected that these would be used the most. - -The "Pipeline" ones are to support Bolt's pipelining features. -Pipelines allow the user to send Neo4j many queries at once and -have them executed by the database concurrently. This is useful -if you have a bunch of queries that aren't necessarily dependant -on one another, and you want to get better performance. The -internal APIs will also pipeline statements where it is able to -reliably do so, but by manually using the pipelining feature -you can maximize your throughput. - -The API provides connection pooling using the `NewDriverPool` method. -This allows you to pass it the maximum number of open connections -to be used in the pool. Once this limit is hit, any new clients will -have to wait for a connection to become available again. - -The sql internalDriver is registered as "neo4j-bolt". The sql.internalDriver interface -is much more limited than what bolt and neo4j supports. In some cases, -concessions were made in order to make that interface work with the -neo4j way of doing things. The main instance of this is the marshalling -of objects to/from the sql.internalDriver.Value interface. In order to support -object types that aren't supported by this interface, the internal encoding -package is used to marshal these objects to byte strings. This ultimately -makes for a less efficient and more 'clunky' implementation. A glaring -instance of this is passing parameters. Neo4j expects named parameters -but the internalDriver interface can only really support positional parameters. -To get around this, the user must create a map[string]interface{} of their -parameters and marshal it to a internalDriver.Value using the encoding.Marshal -function. Similarly, the user must unmarshal data returned from the queries -using the encoding.Unmarshal function, then use type assertions to retrieve -the proper type. - -In most cases the internalDriver will return the data from neo as the proper -go-specific types. For integers they always come back -as int64 and floats always come back as float64. This is for the -convenience of the user and acts similarly to go's JSON interface. -This prevents the user from having to use reflection to get -these values. Internally, the types are always transmitted over -the wire with as few bytes as possible. - -There are also cases where no go-specific type matches the returned values, -such as when you query for a node, relationship, or path. The internalDriver -exposes specific structs which represent this data in the 'structures.graph' -package. There are 4 types - Node, Relationship, UnboundRelationship, and -Path. The internalDriver returns interface{} objects which must have their types -properly asserted to get the data out. +/*Package goBolt implements drivers for the Neo4J Bolt Protocol Versions 1-4. There are some limitations to the types of collections the internalDriver supports. Specifically, maps should always be of type map[string]interface{}