Add documentation about QueryBuilder #1031

alexott · 2018-06-14T14:00:11Z

No description provided.

adutra

This is a very comprehensive guide, truly impressive work.
My remarks are all about style, but please keep in mind that I'm not a native English speaker either, so you might want to get this PR reviewed by someone whose native language is English.

adutra · 2018-07-04T10:33:34Z

manual/statements/built/README.md

@@ -1,5 +1,268 @@
 ## Built statements

-*Coming soon... In the meantime, see the javadoc for [QueryBuilder].*
+Built statements are generated via [QueryBuilder]'s Fluent API.  Use of Fluent API allows


Suggestion: "Use of Fluent API allows for easier build of complex queries, as opposed to the use of hardcoded query strings."

adutra · 2018-07-04T10:34:01Z

manual/statements/built/README.md

Typo: "The provided builders".

adutra · 2018-07-04T10:34:26Z

manual/statements/built/README.md

+invalid queries.
+
+Queries built with `QueryBuilder` are execute the same way as other queries - via


Typo: "are executed"

adutra · 2018-07-04T10:38:37Z

manual/statements/built/README.md

+
+Queries built with `QueryBuilder` are execute the same way as other queries - via
+`execute` or `executeAsync`.  When query is built with putting all data into it, then it


Nit: " When a query is built with inlined values, then it doesn't differ much from a statement specified as a string."

adutra · 2018-07-04T10:39:00Z

manual/statements/built/README.md

+`execute` or `executeAsync`.  When query is built with putting all data into it, then it
+doesn't differ much from statement specified as string.  But it's also possible to build
+the query with bind markers inside it, and then convert it into [prepared statement](../prepared/).


Nit: "into a prepared statement".

adutra · 2018-07-04T11:12:05Z

manual/statements/built/README.md

+
+Specification of conditions is similar to the other operations described above, including
+conditional delete with `ifExists` & `onlyIf`.


Typo: "conditional deletes".

adutra · 2018-07-04T11:12:35Z

manual/statements/built/README.md

+
+If you're repeating the same operation very often, the more effective way will be to
+create the [prepared statement](../prepared/) from the `BuiltStatement`. To do it, instead


Nit: "...create a prepared statement"

adutra · 2018-07-04T11:14:20Z

manual/statements/built/README.md

+If you're repeating the same operation very often, the more effective way will be to
+create the [prepared statement](../prepared/) from the `BuiltStatement`. To do it, instead
+of the real values, use the bind marker that is created either by calling of `bindMarker`


Suggestion: "...use bind markers created either by calling bindMarker (which generates a positional placeholder), or by calling bindMarker("name") (which creates a named placeholder)."

adutra · 2018-07-04T11:15:27Z

manual/statements/built/README.md

+### Setting additional options
+
+As in the case of the usual statements, you can also set additional options for given


Suggestion: "As it is the case for regular statements, you can also set options on built statements such as the consistency level..."

adutra · 2018-07-04T11:16:02Z

manual/statements/built/README.md

+(with `enableTracing`/`disableTracing`), retry policy (with `setRetryPolicy`), etc.
+
+Note: the call to these functions changes the object type from `BuiltStatement` to the


Nit: "from BuiltStatementtoStatementorRegularStatement`"

olim7t

Awesome contribution, thanks!

See a few typos and style suggestions inline.

Also it would be nice to show the generated CQL query for each example, as we did in the driver 4 manual.

olim7t · 2018-07-26T20:21:53Z

manual/statements/built/README.md

+[QueryBuilder]: http://docs.datastax.com/en/drivers/java/3.5/com/datastax/driver/core/querybuilder/QueryBuilder.html
+[TableMetadata]: http://docs.datastax.com/en/drivers/java/3.5/com/datastax/driver/core/TableMetadata.html
+[SchemaBuilder]: https://docs.datastax.com/en/drivers/java/3.5/com/datastax/driver/core/schemabuilder/SchemaBuilder.html


Nit: consistently use https in all URLs.

olim7t · 2018-07-26T20:22:57Z

manual/statements/built/README.md

+
+Queries built with `QueryBuilder` are executed the same way as other queries--via
+`execute` or `executeAsync`.  When query is built with inlined values, then it doesn't


"When a query is built"?

olim7t · 2018-07-26T20:24:24Z

manual/statements/built/README.md

+
+Generation of `BuiltStatement` is easy--start by calling of one of the
+[QueryBuilder]'s methods of that represent the CQL's "verb": `select`, `update`, `delete`,


Superfluous "of"?
"methods that represent"

olim7t · 2018-07-26T20:25:44Z

manual/statements/built/README.md

+Note: The `QueryBuilder` doesn't provide support for the full set of CQL.  For
+DDL operations (`CREATE TABLE`, etc.) you can use the [SchemaBuilder].  To perform other
+operations you still need to use [simple statements](../simple/).


Any example of queries that are neither covered by QueryBuilder nor SchemaBuilder? We try to stay pretty up-to-date...

for example, there is no support for ALTER TYPE,CREATE MATERIALIZED VIEW, roles management, etc.

olim7t · 2018-07-26T20:28:19Z

manual/statements/built/README.md

+Besides selection of the specific columns, there is also a possibility of calling of
+arbitrary CQL function by using the `fcall` (this is just example, don't do this on real
+data):


I would say "calling arbitrary CQL functions by using the fcall method

olim7t · 2018-07-26T20:54:50Z

manual/statements/built/README.md

+### Inserting data
+
+Insertion of data is straightforward--you specify the target table in call to


olim7t · 2018-07-26T20:55:28Z

manual/statements/built/README.md

+```
+
+It also possible to specify additional metadata for inserted data, such as TTL (time to live) or


"It is also possible"

olim7t · 2018-07-26T20:56:37Z

manual/statements/built/README.md

+
+It also possible to specify additional metadata for inserted data, such as TTL (time to live) or
+timestamp.  This is achieved by using the `using` function and providing the `Using`


Maybe you could say "achieved with the using method" to avoid the repetition.

olim7t · 2018-07-26T20:57:46Z

manual/statements/built/README.md

+```
+
+Besides the most often used `set` operation, there is a plenty of operations for work with


"plenty of operations" / "lots of operations"

olim7t · 2018-07-26T21:02:51Z

manual/statements/built/README.md

+Similarly to insert statements, it's also possible to perform conditional updates by
+calling either `ifExists` (to perform the update only if the entry exists), or by calling
+`onlyIf` with a `Clause` object—in this case the row will be updated only if the clause


Nit: use -- like you did in other places

alexott · 2018-07-27T08:50:19Z

Thank you for comments @olim7t ! I've pushed fixes for them...

tolbertam · 2018-08-15T21:30:09Z

Merged, thanks @alexott!

Add documentation about QueryBuilder

cde33a1

tolbertam added this to the 3.6.0 milestone Jun 14, 2018

tolbertam self-requested a review June 14, 2018 14:01

Mention SchemaBuilder for generation of DDL statements

2de1a71

adutra requested changes Jul 4, 2018

View reviewed changes

changes after review & one more pass myself

75f5a49

adutra approved these changes Jul 6, 2018

View reviewed changes

olim7t suggested changes Jul 26, 2018

View reviewed changes

more changes after review

5a4b84e

tolbertam merged commit ce29eea into apache:3.x Aug 15, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation about QueryBuilder #1031

Add documentation about QueryBuilder #1031

alexott commented Jun 14, 2018

adutra left a comment

adutra Jul 4, 2018

adutra Jul 4, 2018

adutra Jul 4, 2018

adutra Jul 4, 2018

adutra Jul 4, 2018

adutra Jul 4, 2018

adutra Jul 4, 2018

adutra Jul 4, 2018

adutra Jul 4, 2018

adutra Jul 4, 2018

olim7t left a comment

olim7t Jul 26, 2018

olim7t Jul 26, 2018

olim7t Jul 26, 2018

olim7t Jul 26, 2018

alexott Jul 27, 2018 •

edited

Loading

olim7t Jul 26, 2018

olim7t Jul 26, 2018

olim7t Jul 26, 2018

olim7t Jul 26, 2018

olim7t Jul 26, 2018

olim7t Jul 26, 2018

alexott commented Jul 27, 2018

tolbertam commented Aug 15, 2018

		invalid queries.

		Queries built with `QueryBuilder` are execute the same way as other queries - via


		Queries built with `QueryBuilder` are execute the same way as other queries - via
		`execute` or `executeAsync`. When query is built with putting all data into it, then it


		Specification of conditions is similar to the other operations described above, including
		conditional delete with `ifExists` & `onlyIf`.


		If you're repeating the same operation very often, the more effective way will be to
		create the [prepared statement](../prepared/) from the `BuiltStatement`. To do it, instead

		### Setting additional options

		As in the case of the usual statements, you can also set additional options for given

		(with `enableTracing`/`disableTracing`), retry policy (with `setRetryPolicy`), etc.

		Note: the call to these functions changes the object type from `BuiltStatement` to the


		Generation of `BuiltStatement` is easy--start by calling of one of the
		[QueryBuilder]'s methods of that represent the CQL's "verb": `select`, `update`, `delete`,

		### Inserting data

		Insertion of data is straightforward--you specify the target table in call to

		```

		It also possible to specify additional metadata for inserted data, such as TTL (time to live) or


		It also possible to specify additional metadata for inserted data, such as TTL (time to live) or
		timestamp. This is achieved by using the `using` function and providing the `Using`

		```

		Besides the most often used `set` operation, there is a plenty of operations for work with

Add documentation about QueryBuilder #1031

Add documentation about QueryBuilder #1031

Conversation

alexott commented Jun 14, 2018

adutra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

olim7t left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexott Jul 27, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexott commented Jul 27, 2018

tolbertam commented Aug 15, 2018

alexott Jul 27, 2018 •

edited

Loading