Solr
  1. Solr
  2. SOLR-8659 Improve Solr JDBC Driver to support more SQL Clients
  3. SOLR-8521

Add documentation for how to use Solr JDBC driver with SQL client like DB Visualizer

    Details

    • Type: Sub-task Sub-task
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 6.0
    • Fix Version/s: None
    • Component/s: documentation, SolrJ
    • Labels:
      None

      Description

      Currently this requires the following:

      • a JDBC SQL client program (like DBVisualizer or SQuirrelSQL)
      • all jars from solr/dist/solrj-lib/* to be on the SQL client classpath
      • solr/dist/solr-solrj-6.0.0-SNAPSHOT.jar on the SQL client classpath
      • a valid JDBC connection string (like jdbc:solr://SOLR_ZK_CONNECTION_STRING?collection=COLLECTION_NAME)
      • without SOLR-8213, the username/password supplied by the SQL client will be ignored.
      1. dbvisualizer_solrjdbc.zip
        2.37 MB
        Kevin Risden
      2. solr_jdbc_dbvisualizer_20160203.pdf
        5.36 MB
        Kevin Risden

        Issue Links

          Activity

          Hide
          Kevin Risden added a comment -

          Attached first pass at documentation with screenshots. This PDF comes terribly formatted from an export from an internal Confluence. It has all the information just the pictures make the page breaks ugly. This should look a lot better on the Solr Confluence when it can eventually be migrated there.

          Show
          Kevin Risden added a comment - Attached first pass at documentation with screenshots. This PDF comes terribly formatted from an export from an internal Confluence. It has all the information just the pictures make the page breaks ugly. This should look a lot better on the Solr Confluence when it can eventually be migrated there.
          Hide
          Joel Bernstein added a comment - - edited

          Ok looks great! I'll try out the steps.

          Cassandra Targett, do you think this belongs in the Solr user guide? I think eventually we could add a guide for other clients such as Tableue and Spotfire. Possible we could add a new section called JDBC Clients

          Show
          Joel Bernstein added a comment - - edited Ok looks great! I'll try out the steps. Cassandra Targett , do you think this belongs in the Solr user guide? I think eventually we could add a guide for other clients such as Tableue and Spotfire. Possible we could add a new section called JDBC Clients
          Hide
          Cassandra Targett added a comment - - edited

          Yes, I do think it should be in the Ref Guide - it's something general users may want, so we should guide them on how to connect it. The PDF attached is mostly screenshots - if the hope is that the Ref Guide will show screenshots, it would be helpful if those were attached directly to the issue. I don't know that the page makes sense with that many step-by-step screenshots - we don't even have that many covering the Admin UI, and DBVisualizer is not an application developed by this community - but a few key ones would probably be helpful.

          As for where it should go, I wonder if we should take a step back and think about the overall organization of docs for this new features. My current understanding is that the JDBC client is only used with Parallel SQL features, but is it more than that (either today or intended to be more in the future)? If so, we should spend a minute or two thinking about the use cases to figure out the best place for a new section.

          edit: by the way, I don't mean to dismiss the effort to make those screenshots, they are very helpful and clear.

          Show
          Cassandra Targett added a comment - - edited Yes, I do think it should be in the Ref Guide - it's something general users may want, so we should guide them on how to connect it. The PDF attached is mostly screenshots - if the hope is that the Ref Guide will show screenshots, it would be helpful if those were attached directly to the issue. I don't know that the page makes sense with that many step-by-step screenshots - we don't even have that many covering the Admin UI, and DBVisualizer is not an application developed by this community - but a few key ones would probably be helpful. As for where it should go, I wonder if we should take a step back and think about the overall organization of docs for this new features. My current understanding is that the JDBC client is only used with Parallel SQL features, but is it more than that (either today or intended to be more in the future)? If so, we should spend a minute or two thinking about the use cases to figure out the best place for a new section. edit : by the way, I don't mean to dismiss the effort to make those screenshots, they are very helpful and clear.
          Hide
          Joel Bernstein added a comment - - edited

          That is correct the JDCB driver only works with the Parallel SQL feature.

          Show
          Joel Bernstein added a comment - - edited That is correct the JDCB driver only works with the Parallel SQL feature.
          Hide
          Kevin Risden added a comment -

          The PDF attached is mostly screenshots - if the hope is that the Ref Guide will show screenshots, it would be helpful if those were attached directly to the issue. I don't know that the page makes sense with that many step-by-step screenshots - we don't even have that many covering the Admin UI, and DBVisualizer is not an application developed by this community - but a few key ones would probably be helpful.

          I agree that it is probably too many screenshots for a general purpose reference guide. The rough outline of steps in the description is really what is required for connecting any JDBC SQL client. I wanted the first guide to be extra clear to start with and then can trim down the unnecessary steps. I'm thinking about writing a blog post about this and that would probably be a better place for a step-by-step guide.

          As a side note: the screenshots will have to be updated with a non snapshot build of Solr. It would make sense to take the final screenshots maybe once an RC is cut or at least update the screenshots at that time.

          Show
          Kevin Risden added a comment - The PDF attached is mostly screenshots - if the hope is that the Ref Guide will show screenshots, it would be helpful if those were attached directly to the issue. I don't know that the page makes sense with that many step-by-step screenshots - we don't even have that many covering the Admin UI, and DBVisualizer is not an application developed by this community - but a few key ones would probably be helpful. I agree that it is probably too many screenshots for a general purpose reference guide. The rough outline of steps in the description is really what is required for connecting any JDBC SQL client. I wanted the first guide to be extra clear to start with and then can trim down the unnecessary steps. I'm thinking about writing a blog post about this and that would probably be a better place for a step-by-step guide. As a side note: the screenshots will have to be updated with a non snapshot build of Solr. It would make sense to take the final screenshots maybe once an RC is cut or at least update the screenshots at that time.
          Hide
          Yonik Seeley added a comment -

          It feels like this is where linear documentation (i.e. a produced PDF where you get/download everything) starts to diverge from non-linear (web/wiki)...
          hundreds of pages of screenshots can be completely natural on on the latter, but not so much on the former.

          Also

          • The systems connecting to solr may change versions as well
          • New systems may be added at any point and be applicable to multiple versions of Solr (it's not like we can document them all up-front)

          Live documentation feels like the best fit for this. Regardless of what Solr version people are using, it seems like they tend to go look at the latest version of cwiki anyway. If that's the case, the question may just boil down to: do we want to put this somewhere on the wiki that doesn't get serialized to a PDF?

          That is correct the JDCB driver only works with the Parallel SQL feature.

          How users will come to see it is: "I can use JDBC to talk to Solr" (and of course the language is SQL when using JDBC). It will be seen as a first class feature, and the fact that we were not able to do that until just recently will be irrelevant.

          Show
          Yonik Seeley added a comment - It feels like this is where linear documentation (i.e. a produced PDF where you get/download everything) starts to diverge from non-linear (web/wiki)... hundreds of pages of screenshots can be completely natural on on the latter, but not so much on the former. Also The systems connecting to solr may change versions as well New systems may be added at any point and be applicable to multiple versions of Solr (it's not like we can document them all up-front) Live documentation feels like the best fit for this. Regardless of what Solr version people are using, it seems like they tend to go look at the latest version of cwiki anyway. If that's the case, the question may just boil down to: do we want to put this somewhere on the wiki that doesn't get serialized to a PDF? That is correct the JDCB driver only works with the Parallel SQL feature. How users will come to see it is: "I can use JDBC to talk to Solr" (and of course the language is SQL when using JDBC). It will be seen as a first class feature, and the fact that we were not able to do that until just recently will be irrelevant.
          Hide
          Cassandra Targett added a comment -

          Live documentation feels like the best fit for this. Regardless of what Solr version people are using, it seems like they tend to go look at the latest version of cwiki anyway. If that's the case, the question may just boil down to: do we want to put this somewhere on the wiki that doesn't get serialized to a PDF?

          We have no model today for documentation that is "online only". The online version of the Ref Guide is always a draft for the next release; the real Ref Guide is actually the PDF. I happen to agree with you that most users would prefer an online version instead of a giant PDF, but there are reasons why it isn't like that and real obstacles to making it like that.

          I get your overall point - a full screenshot-by-screenshot walkthrough is somewhat heavy in the PDF and works better in an online version, but I don't see the harm in adding a couple of screenshots using one client as an example with the way we've got things today. The docs will need to avoid any client-specific details anyway, at least in a section that applies to all clients, even if there is a section that covers a specific client in more detail.

          Show
          Cassandra Targett added a comment - Live documentation feels like the best fit for this. Regardless of what Solr version people are using, it seems like they tend to go look at the latest version of cwiki anyway. If that's the case, the question may just boil down to: do we want to put this somewhere on the wiki that doesn't get serialized to a PDF? We have no model today for documentation that is "online only". The online version of the Ref Guide is always a draft for the next release; the real Ref Guide is actually the PDF. I happen to agree with you that most users would prefer an online version instead of a giant PDF, but there are reasons why it isn't like that and real obstacles to making it like that. I get your overall point - a full screenshot-by-screenshot walkthrough is somewhat heavy in the PDF and works better in an online version, but I don't see the harm in adding a couple of screenshots using one client as an example with the way we've got things today. The docs will need to avoid any client-specific details anyway, at least in a section that applies to all clients, even if there is a section that covers a specific client in more detail.
          Hide
          Kevin Risden added a comment -

          Was there consensus on where the documentation should go? Reference guide or maybe the wiki? My compromise is below:

          Reference guide: generic guide on what is required to use SolrJ JDBC (no screenshots)
          Wiki: screenshot-by-screenshot walkthough with a page per client (DbVisualizer, SQuirrel SQL, Apache Zeppelin, etc)?

          I plan to write some blog posts about how to use each of these as well in the next few weeks.

          Show
          Kevin Risden added a comment - Was there consensus on where the documentation should go? Reference guide or maybe the wiki? My compromise is below: Reference guide: generic guide on what is required to use SolrJ JDBC (no screenshots) Wiki: screenshot-by-screenshot walkthough with a page per client (DbVisualizer, SQuirrel SQL, Apache Zeppelin, etc)? I plan to write some blog posts about how to use each of these as well in the next few weeks.
          Hide
          Joel Bernstein added a comment -

          I think the generic guide makes sense on the CWIKI for sure.

          I also think the screen shot guides belong on the CWIKI as well. Just in separate sub-pages.

          Show
          Joel Bernstein added a comment - I think the generic guide makes sense on the CWIKI for sure. I also think the screen shot guides belong on the CWIKI as well. Just in separate sub-pages.
          Hide
          Kevin Risden added a comment -

          Adding a note that the material here and related tickets need to be integrated with the Solr Reference Guide here: https://cwiki.apache.org/confluence/display/solr/Parallel+SQL+Interface#ParallelSQLInterface-SQLClientsandDatabaseVisualizationTools

          Show
          Kevin Risden added a comment - Adding a note that the material here and related tickets need to be integrated with the Solr Reference Guide here: https://cwiki.apache.org/confluence/display/solr/Parallel+SQL+Interface#ParallelSQLInterface-SQLClientsandDatabaseVisualizationTools
          Hide
          Kevin Risden added a comment -

          Adding images I used for a post on this topic (here and here). Planning to create CWIKI page shortly.

          Show
          Kevin Risden added a comment - Adding images I used for a post on this topic ( here and here ). Planning to create CWIKI page shortly.
          Show
          Kevin Risden added a comment - Added page to CWIKI: https://cwiki.apache.org/confluence/display/solr/Solr+JDBC+-+DbVisualizer
          Hide
          Cassandra Targett added a comment -

          Picking up the screenshot conversation again...

          In prepping the Ref Guide for 6.1 release, I noticed that the PDF for 6.1 is 17.8 Mb in size, while the 6.0 version was 9.5Mb. Adding up the sizes of all the images added for DBVisualizer, Squirrel, and Zeppelin, they account for ~6Mb of the added size. There are an additional 42 pages of PDF, bringing the whole thing to over 700 pages.

          I would like to resize some of the screenshots so they are smaller (when it's possible to do so without losing their value), and take a look at omitting some to replace them with text (again, where the screenshot doesn't add a lot of extra value). I appreciate the visual walk-through, but think we could possibly "tell the tale", as it were, without as many screenshots. I won't delete any, so if I screw it up at all and we need to add any back, we can do so. Just wanted to give you a heads up Kevin Risden in case you had a different point of view.

          Show
          Cassandra Targett added a comment - Picking up the screenshot conversation again... In prepping the Ref Guide for 6.1 release, I noticed that the PDF for 6.1 is 17.8 Mb in size, while the 6.0 version was 9.5Mb. Adding up the sizes of all the images added for DBVisualizer, Squirrel, and Zeppelin, they account for ~6Mb of the added size. There are an additional 42 pages of PDF, bringing the whole thing to over 700 pages. I would like to resize some of the screenshots so they are smaller (when it's possible to do so without losing their value), and take a look at omitting some to replace them with text (again, where the screenshot doesn't add a lot of extra value). I appreciate the visual walk-through, but think we could possibly "tell the tale", as it were, without as many screenshots. I won't delete any, so if I screw it up at all and we need to add any back, we can do so. Just wanted to give you a heads up Kevin Risden in case you had a different point of view.
          Hide
          Jan Høydahl added a comment -

          I vote for Kevin's compromise:

          Reference guide: generic guide on what is required to use SolrJ JDBC (no screenshots)
          Wiki: screenshot-by-screenshot walkthough with a page per client (DbVisualizer, SQuirrel SQL, Apache Zeppelin, etc)?

          It would also be ok to simply link to the existing blog posts from the refguide, we already do that for other features.

          Show
          Jan Høydahl added a comment - I vote for Kevin's compromise: Reference guide: generic guide on what is required to use SolrJ JDBC (no screenshots) Wiki: screenshot-by-screenshot walkthough with a page per client (DbVisualizer, SQuirrel SQL, Apache Zeppelin, etc)? It would also be ok to simply link to the existing blog posts from the refguide, we already do that for other features.
          Hide
          Cassandra Targett added a comment -

          I vote for Kevin's compromise:
          Reference guide: generic guide on what is required to use SolrJ JDBC (no screenshots)
          Wiki: screenshot-by-screenshot walkthough with a page per client (DbVisualizer, SQuirrel SQL, Apache Zeppelin, etc)?

          OK, thanks for the feedback. Since all I really have time for right now is editing the Ref Guide, and I'm already days behind on that for 6.1, I'll focus on that and if you or others want wiki pages, you can figure that part out as you have time to make it happen.

          Show
          Cassandra Targett added a comment - I vote for Kevin's compromise: Reference guide: generic guide on what is required to use SolrJ JDBC (no screenshots) Wiki: screenshot-by-screenshot walkthough with a page per client (DbVisualizer, SQuirrel SQL, Apache Zeppelin, etc)? OK, thanks for the feedback. Since all I really have time for right now is editing the Ref Guide, and I'm already days behind on that for 6.1, I'll focus on that and if you or others want wiki pages, you can figure that part out as you have time to make it happen.
          Hide
          Kevin Risden added a comment -

          Cassandra Targett Thanks for the heads up and agree the screenshots might have been too big. Feel free to adjust/modify as you see fit. I can take a stab at moving the images to the wiki and out of the reference guide in the next few weeks if that helps.

          Show
          Kevin Risden added a comment - Cassandra Targett Thanks for the heads up and agree the screenshots might have been too big. Feel free to adjust/modify as you see fit. I can take a stab at moving the images to the wiki and out of the reference guide in the next few weeks if that helps.

            People

            • Assignee:
              Kevin Risden
              Reporter:
              Kevin Risden
            • Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development