Details

    • Sub-task
    • Status: Resolved
    • Normal
    • Resolution: Fixed
    • 1.1.2
    • Legacy/CQL

    Description

      The language doc (doc/cql/CQL.textile) needs to be forked for CQLv3 and updated accordingly.

      Attachments

        Activity

          I've forked and update the doc at https://github.com/pcmanus/cassandra/commits/3779.

          Note that this is a pretty extensive rewrite, but I wanted to make sure it reflected the code and typically rewriting the grammar parts was simpler than checking all the diffs. The doc is also reorganized (and imho improved by it). I've also played with the CSS, but if others don't like it, I'll just keep that CSS for my own use

          Going through that also make made remark a few inconsistency here and there in the code. I've noted those down and will open tickets for those, but I've sometimes redacted the doc as if those were fixed. If one of those small fixes/change don't make it, I'll update the doc accordingly. Besides, CQL3 is beta so so is the doc so far.

          Please don't hesitate to voice criticism and other complains.

          slebresne Sylvain Lebresne added a comment - I've forked and update the doc at https://github.com/pcmanus/cassandra/commits/3779 . Note that this is a pretty extensive rewrite, but I wanted to make sure it reflected the code and typically rewriting the grammar parts was simpler than checking all the diffs. The doc is also reorganized (and imho improved by it). I've also played with the CSS, but if others don't like it, I'll just keep that CSS for my own use Going through that also make made remark a few inconsistency here and there in the code. I've noted those down and will open tickets for those, but I've sometimes redacted the doc as if those were fixed. If one of those small fixes/change don't make it, I'll update the doc accordingly. Besides, CQL3 is beta so so is the doc so far. Please don't hesitate to voice criticism and other complains.
          slebresne Sylvain Lebresne added a comment - - edited

          Forgot to say: The doc is trying to stick to a vocabulary that I think make sense for CQL3. In particular, it does not respect the current Cassandra vocabulary. For instance, the notion of column and row in the document are the ones of SQL, not the one of our internal representation. I also use the term table instead of column family systematically. While I understand this may be confusing for current users of Cassandra, I think this happens to be a very good fit to CQL3 and imho trying to do otherwise would make it very hard to explain CQL3. Besides, I doubt Cassandra users have already forgotten the notion of columns and rows in SQL, so the confusion should be minimal as long as we make the context clear.

          But this means I'll probably add a small warning at the beginning of the doc.

          slebresne Sylvain Lebresne added a comment - - edited Forgot to say: The doc is trying to stick to a vocabulary that I think make sense for CQL3. In particular, it does not respect the current Cassandra vocabulary. For instance, the notion of column and row in the document are the ones of SQL, not the one of our internal representation. I also use the term table instead of column family systematically. While I understand this may be confusing for current users of Cassandra, I think this happens to be a very good fit to CQL3 and imho trying to do otherwise would make it very hard to explain CQL3. Besides, I doubt Cassandra users have already forgotten the notion of columns and rows in SQL, so the confusion should be minimal as long as we make the context clear. But this means I'll probably add a small warning at the beginning of the doc.

          I pushed another commit on https://github.com/pcmanus/cassandra/commits/3779-v2 (I messed up my original branch so pushed a new one with both the old and new commit) to:

          • update the doc with the last cql3 changes
          • add 2 sentences at the beginning to explain that rows and columns are used in the sense of SQL
          • add a small banner at the beginning to remind people that CQL3 is beta currently.
          slebresne Sylvain Lebresne added a comment - I pushed another commit on https://github.com/pcmanus/cassandra/commits/3779-v2 (I messed up my original branch so pushed a new one with both the old and new commit) to: update the doc with the last cql3 changes add 2 sentences at the beginning to explain that rows and columns are used in the sense of SQL add a small banner at the beginning to remind people that CQL3 is beta currently.

          Any news on the review of this? I think it would be nice to get the doc out quickly (even if it's not perfect).

          slebresne Sylvain Lebresne added a comment - Any news on the review of this? I think it would be nice to get the doc out quickly (even if it's not perfect).
          urandom Eric Evans added a comment - - edited

          Sorry. I plan to have a look over the next few days, but if you get tired of waiting, I see no reason not to post them (any docs are better than no docs).

          urandom Eric Evans added a comment - - edited Sorry. I plan to have a look over the next few days, but if you get tired of waiting, I see no reason not to post them (any docs are better than no docs).

          So I did commit that (with a few minor change to account for the last evolutions of CQL3). I'll wait a few days in case somewhat wants to do some proof-reading, but then I'll put it accessible from http://cassandra.apache.org/download/ (like the one for CQL2).

          slebresne Sylvain Lebresne added a comment - So I did commit that (with a few minor change to account for the last evolutions of CQL3). I'll wait a few days in case somewhat wants to do some proof-reading, but then I'll put it accessible from http://cassandra.apache.org/download/ (like the one for CQL2).

          People

            slebresne Sylvain Lebresne
            urandom Eric Evans
            Sylvain Lebresne
            Eric Evans
            Votes:
            1 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: