Update "Getting Started" documentation #2028

asvetlik · 2019-06-28T16:48:23Z

Overview

This will redo the current Getting Started on the Pilosa website. It is adding Go, Java, and Python and removing Docker.

Pull request checklist

I have read the contributing guide.
I have agreed to the Contributor License Agreement.
I have updated the documentation.
I have resolved any merge conflicts.
I have included tests that cover my changes.
All new and existing tests pass.
Make sure PR title conforms to convention in CHANGELOG.md.
Add appropriate changelog label to PR (if applicable).

Code review checklist

This is the checklist that the reviewer will follow while reviewing your pull request. You do not need to do anything with this checklist, but be aware of what the reviewer will be looking for.

Ensure that any changes to external docs have been included in this pull request.
If the changes require that minor/major versions need to be updated, tag the PR appropriately.
Ensure the new code is properly commented and follows Idiomatic Go.
Check that tests have been written and that they cover the new functionality.
Run tests and ensure they pass.
Build and run the code, performing any applicable integration testing.
Make sure PR title conforms to convention in CHANGELOG.md.
Make sure PR is tagged with appropriate changelog label.

asvetlik · 2019-06-28T16:51:33Z

Under the "Using Java" section and under the "Creating the Environment" subsection, you have to make some edits to the pom.xml file. I want to bold or change the color of the specific changes that need to be made, but I don't know how. Also, should I just change the pom.xml file that is in the official getting-started repository and remove the whole need to edit in the first place?

asvetlik · 2019-06-28T17:08:21Z

I realized why I didn't just edit the pom.xml file and make a pull request. I can do a pull request and update the version, but the StarTrace.py file in the Getting Started is different than the startrace.py file in the getting-started repository and the way the mainClass is called is different for each.

alanbernstein · 2019-06-28T18:00:35Z

docs/getting-started.md

     "What's Next?",
 ]
 +++

 ## Getting Started

 Pilosa supports an HTTP interface which uses JSON by default.
-Any HTTP tool can be used to interact with the Pilosa server. The examples in this documentation will use [curl](https://curl.haxx.se/) which is available by default on many UNIX-like systems including Linux and MacOS. Windows users can download curl [here](https://curl.haxx.se/download.html).
+Any HTTP tool can be used to interact with the Pilosa server. The examples in this documentation will use curl which is available by default on many UNIX-like systems including Linux and MacOS. However, the best way to interface with the Pilosa server is through one of our three client libraries. Pilosa currently supports [Go](https://github.com/pilosa/go-pilosa), [Java](https://github.com/pilosa/java-pilosa), and [Python](https://github.com/pilosa/python-pilosa).


"one of our three official client libraries" - we do have others, but we focus on these three because they're full-featured, and we keep them up to date.

alanbernstein · 2019-06-28T18:03:05Z

docs/getting-started.md


-#### Create the Schema
+Pilosa supports curl (or any HTTP tool), Go, Java, and Python. In this project, we will walk you through how to use each one to best communicate with the Pilosa server.


I'm going to continue with some pedantic comments for a while: The wording is a bit off here - Pilosa the organization supports the development of the go-pilosa, java-pilosa and python-pilosa client libraries, but Pilosa the server supports any client that can send requests to it.

alanbernstein · 2019-06-28T18:04:39Z

docs/getting-started.md

@@ -56,14 +55,20 @@ curl localhost:10101/schema
 {"indexes":null}


We should update this to show a non-null response - maybe a response after importing is complete, and a note explaining that.

alanbernstein · 2019-06-28T18:18:23Z

docs/getting-started.md

+
+##### Create the Environment
+
+In order to communicate with Pilosa through your Go code, you must have a "translator," which is go-pilosa. To install go-pilosa, open a terminal (one other than the one running Pilosa) and download the library in your `GOPATH` using:


We don't normally use the term "translator" for this, and it does have another meaning in the context of Pilosa - "client" would be a better term.

alanbernstein · 2019-06-28T18:19:13Z

docs/getting-started.md

+
+To contain the Getting Started project in one place, we will create a new folder as follows:
+```
+mkdir GettingStarted && cd GettingStarted


I'd suggest getting-started for consistency with the repo. (also because I just prefer lower case filenames)

alanbernstein · 2019-06-28T18:19:36Z

docs/getting-started.md

+curl -O https://raw.githubusercontent.com/pilosa/getting-started/master/language.csv
+```
+
+We will also create a file called `StarTrace.go` as follows:


I'd suggest startrace.go for consistency, plus go naming conventions.

alanbernstein · 2019-06-28T18:30:37Z

docs/getting-started.md

+```
+stargazer = repository.field("stargazer", time_quantum=pilosa.TimeQuantum.YEAR_MONTH_DAY)
+```
+Since our data contains time stamps which represent the time users starred repos, we establish the time aspect by using `time_quantum`. Time quantum is the resolution of the time we want to use, and we set it to `YEAR_MONTH-DAY` for `stargazer`.


YEAR_MONTH-DAY looks like a typo

alanbernstein · 2019-06-28T18:35:41Z

docs/getting-started.md

@@ -232,7 +224,682 @@ curl localhost:10101/index/repository/query \
 Please note that while user ID 99999 may not be sequential with the other column IDs, it is still a relatively low number. 
 Don't try to use arbitrary 64-bit integers as column or row IDs in Pilosa - this will lead to problems such as poor performance and out of memory errors.

+#### Using Go
+
+Pilosa requires Go 1.12 or higher. It is also recommended that you have a code editor downloaded.


This might be personal preference, but I think we can leave out the "code editor" recommendation.

alanbernstein · 2019-06-28T18:37:15Z

docs/getting-started.md

+
+##### Create the Environment
+
+In order to communicate with Pilosa through your Go code, you must have a "translator," which is go-pilosa. To install go-pilosa, open a terminal (one other than the one running Pilosa) and download the library in your `GOPATH` using:


"download the library to your GOPATH"

alanbernstein · 2019-06-28T18:40:07Z

docs/getting-started.md

+
+##### Create the Schema
+
+Before we can import data or run queries, we need to create our schema. Go-pilosa is implemented by importing `github.com/pilosa/go-pilosa` and its ability to read csv files is implemented by importing 'github.com/pilosa/go-pilosa/csv`. The first steps to creating the schema are creating a client which will communicate our schema to Pilosa, creating a schema which will contain our indexes and fields, and syncing with Pilosa. This is all done in the `StarTrace.go` file:


"implemented" is not quite the right term to use here. I'd suggest something like

"You can see two imports from the go-pilosa repo, go-pilosa for the client, and csv for the CSV reader."

alanbernstein · 2019-06-28T18:41:17Z

docs/getting-started.md

+
+##### Create the Schema
+
+Before we can import data or run queries, we need to create our schema. Go-pilosa is implemented by importing `github.com/pilosa/go-pilosa` and its ability to read csv files is implemented by importing 'github.com/pilosa/go-pilosa/csv`. The first steps to creating the schema are creating a client which will communicate our schema to Pilosa, creating a schema which will contain our indexes and fields, and syncing with Pilosa. This is all done in the `StarTrace.go` file:


I think those three steps are all of the steps in creating the schema - I'd phrase this as something like "Create the schema on the Pilosa server by first creating a client, defining the schema locally, then syncing with Pilosa".

alanbernstein · 2019-06-28T18:43:16Z

docs/getting-started.md

+		log.Fatal(err)
+	}
+```
+Since our `stargazer` data contains time stamps, which represent the time users starred repos, we will be using the `csv.NewColumnIteratorWithTimeStampFormat` function that is built into the go-pilosa import. This function takes the format of the csv files (`csv.RowIDColumnID`), an `io.Reader` (`bytes.NewReader(stargazerFile)`), and the time quantum format (`format`) and translates the csv file into a format Pilosa can read. Time quantum is the resolution of the time we want to use.


instead of "that is built into the go-pilosa import", we can say "from the go-pilosa/csv package"

alanbernstein · 2019-07-01T20:40:08Z

docs/getting-started.md

+
+##### Create the Environment
+
+In order to communicate with Pilosa through your Go code, you must have a client, which is go-pilosa. To install go-pilosa, open a terminal (one other than the one running Pilosa) and download the library to your `GOPATH` using:


Interacting with Pilosa in your go program is best accomplished using our client, go-pilosa. Install go-pilosa (in a new terminal) and download ...

alanbernstein · 2019-07-01T20:40:40Z

docs/getting-started.md

+go get github.com/pilosa/go-pilosa
+```
+
+To contain the Getting Started project in one place, we will create a new folder as follows:


Create a project folder:

alanbernstein · 2019-07-01T21:05:02Z

docs/getting-started.md

+
+We will now create the java directory that will contain our `startrace.java` file and create the `startrace.java` file:
+```
+mkdir src && cd src


mkdir -p src/main/java && cd src/main/java
touch startrace.go

alanbernstein · 2019-07-02T15:11:30Z

docs/getting-started.md

@@ -227,18 +266,18 @@ Don't try to use arbitrary 64-bit integers as column or row IDs in Pilosa - this

 #### Using Go

-Pilosa requires Go 1.12 or higher.
+Pilosa supports the two most recent versions of Go.


"Pilosa follows the Go policy of supporting the two most recent major versions of Go."

FYI, as explained here: https://golang.org/doc/devel/release.html. The "major" is meaningful here.

alanbernstein · 2019-07-02T15:22:16Z

docs/getting-started.md

-import com.pilosa.client.TimeQuantum;
-```
-Create the schema by creating a client which will communicate our schema to Pilosa, creating a schema which will contain our indexes and fields, and syncing with Pilosa. This is all done in the `startrace.java` file:
+Before we can import data or run queries, we need to create our schema. The first 6 dependencies are imported from the java-pilosa library. Create the schema by creating a client which will communicate our schema to Pilosa, creating a schema which will contain our indexes and fields, and syncing with Pilosa. This is all done in the `StarTrace.java` file:


"6" should be "six". This is one of those silly style rules that I don't really believe in, but follow compulsively.

This paragraph can also be changed to match the update in the corresponding part of the Go section (line 297)

I changed it to be "You can see the first six dependencies are imported from the java-pilosa library." I also made the same change to the Python section

alanbernstein · 2019-07-02T15:29:17Z

docs/getting-started.md

@@ -44,17 +44,48 @@ In order to better understand Pilosa's capabilities, we will create a sample pro

 Although Pilosa doesn't keep the data in a tabular format, we still use the terms "columns" and "rows" when describing the data model. We put the primary objects in columns, and the properties of those objects in rows. For example, the Star Trace project will contain an index called "repository" which contains columns representing Github repositories, and rows representing properties like programming languages and stargazers. We can better organize the rows by grouping them into sets called Fields. So the "repository" index might have a "languages" field as well as a "stargazers" field. You can learn more about indexes and fields in the [Data Model](../data-model/) section of the documentation.

-Pilosa as an organization supports curl (or any HTTP tool), Go, Java, and Python. However, Pilosa as a server will support any client that can send requests to it. In this project, we will walk you through how to use each one to best communicate with the Pilosa server.
+Pilosa officially supports curl (or any HTTP tool), Go, Java, and Python, however it will accept any client that can send requests to it. In this project, we will walk you through how to use each one to best communicate with the Pilosa server.


The wording is still a bit off here - Pilosa doesn't really know anything about curl specifically.

"Pilosa officially supports three client libraries, for Go, Java and Python. You can also use any HTTP client, such as curl, for quick testing, but official client libraries are the preferred method in production code."

I'd say after making this change, the note below ("Note: This is not the recommended way to interact with Pilosa, but it is the fastest way to see the efficiency of Pilosa.") is no longer needed.

What was that wording book you were referencing again? I may need to read it 😅

alanbernstein · 2019-07-02T19:58:35Z

docs/getting-started.md

     "What's Next?",
 ]
 +++

 ## Getting Started

 Pilosa supports an HTTP interface which uses JSON by default.
-Any HTTP tool can be used to interact with the Pilosa server. The examples in this documentation will use [curl](https://curl.haxx.se/) which is available by default on many UNIX-like systems including Linux and MacOS. Windows users can download curl [here](https://curl.haxx.se/download.html).
+Any HTTP tool can be used to interact with the Pilosa server. The examples in this documentation will use curl which is available by default on many UNIX-like systems including Linux and MacOS. However, the best way to interface with the Pilosa server is through one of our three official client libraries. Pilosa currently supports [Go](https://github.com/pilosa/go-pilosa), [Java](https://github.com/pilosa/java-pilosa), and [Python](https://github.com/pilosa/python-pilosa).


I just realized this paragraph, and the one at line 47, are kind of redundant. Is there a reason for repeating this information?

This is a paragraph from the original Getting Started file that I edited to fit what we were doing. I don't think we actually need it. I can remove it and then take the Open File Limit comment out of the flag.

We should remove one of them, but it seems like a good summary intro for the whole page, so I kind of like it at the beginning.

I don't think the note about the open file limit needs to be changed.

alanbernstein · 2019-07-02T19:59:52Z

docs/getting-started.md

 ```
+Note: This is the response you should receive once completing this project. It has also been formatted using `jq`.


We have a "Note" section both before and after the code sample above. Let's combine these into one section, and put it above the code sample. We can also give it special formatting - see line 20 for an example.

alanbernstein · 2019-07-03T17:18:37Z

docs/getting-started.md

-If at any time you want to verify the data structure, you can request the schema as follows:
+<div class="note">
+ <p>If at any time you want to verify the data structure, you can request the schema as follows:<\p>
+<\div>


This should be a forward slash, not a backslash (also the <\p> tag). Backslashes are used mostly as "escape characters", it is usually good to avoid them unless you know they are required for something.

alanbernstein · 2019-07-03T17:23:15Z

docs/getting-started.md

 ```
+<div class="note">
+	<p>Note: This is the response you should receive once completing this project. It has also been formatted using `jq`. <\p>


the backticks (around jq) don't work inside the div note section. <code>jq</code> would work. It might also be nice to have that be a link to the program site (https://stedolan.github.io/jq/)

alanbernstein · 2019-07-03T17:26:57Z

docs/getting-started.md

 ``` request
 curl localhost:10101/index/repository -X POST
 ```
 ``` response
 {"success":true}
 ```
-The index name must be 64 characters or less, start with a letter, and consist only of lowercase alphanumeric characters or `_-`.
+The index name must be 64 characters or less, start with a letter, and consist only of lowercase alphanumeric characters or `_-`. The same goes for field names.


This is a grammar rule that I can never remember properly, but I think the "less" here should be "fewer". If you can verify that, let's change this and other occurrences.

You are correct. Dictionary.com says that fewer should be used for countable things while less should be used for "singular mass nouns." For example, fewer ingredients and less salt.

alanbernstein · 2019-07-03T17:30:30Z

docs/getting-started.md

+            .build();
+        Field stargazer = repository.field("stargazer", stargazerOptions);
+```
+Since our data contains time stamps which represent the time users starred repos, we set the field type to `time` using `fieldTime()`. Time quantum is the resolution of the time we want to use, and we set it to `YEAR_MONTH-DAY` for `stargazer`.


YEAR_MONTH-DAY should be YEAR_MONTH_DAY

alanbernstein · 2019-07-03T17:33:20Z

docs/getting-started.md

+python3 -m venv startrace
+```
+
+Next, we activate the python environment we created and install the requirements (and python-pilosa):


no need for the "and" in "and python-pilosa". the requirements file contains only a single dependency, which is the python package called "pilosa", implemented in the repository named "python-pilosa".

So should it be:
Next we activate the python environment we created and install the requirements for python-pilosa.
?

"Next, we activate the python environment we created and install the single dependency, python-pilosa"

or

"Next, we activate the python environment we created and install python-pilosa"

The requirements are for the current project, getting-started. The requirements are a list of dependencies, in this case including only one item.

alanbernstein

Looks good!

asvetlik added 7 commits June 25, 2019 13:34

Removed pilosa import and added go

59e94b4

Merge branch 'master' of https://github.com/asvetlik/pilosa

4b0962b

Reformatted and added HTTP

7e9fed8

Fixed typos

66867b0

Added Java and Fixed Typos

93da23d

Added Python

74cfa79

Added explanation and fixed typos

680b011

asvetlik requested a review from jaffee June 28, 2019 16:48

asvetlik closed this Jun 28, 2019

asvetlik reopened this Jun 28, 2019

asvetlik requested a review from alanbernstein June 28, 2019 17:13

Added the Sample Project subsections to left nav area

9d7273e

alanbernstein reviewed Jun 28, 2019

View reviewed changes

Revised to include review comments

c8e68c8

alanbernstein reviewed Jul 1, 2019

View reviewed changes

Made syntax, format, and wording corrections

636c7d2

alanbernstein reviewed Jul 2, 2019

View reviewed changes

Improved documentation wording

f40958f

alanbernstein reviewed Jul 2, 2019

View reviewed changes

asvetlik added 4 commits July 2, 2019 15:21

Removed Note before schema check

36c75ea

Made Schema check into note

f991df2

Fixed Schema check note

e389837

Deleted redundant paragraph in Sample Project

614bcff

alanbernstein reviewed Jul 3, 2019

View reviewed changes

asvetlik added 3 commits July 3, 2019 13:52

Made review chnages

daad23b

Reformatted Schema Check

2db061a

Fixed jq note link

c6e840e

alanbernstein approved these changes Jul 3, 2019

View reviewed changes

Merge branch 'master' into master

42a1d85

asvetlik merged commit c2cbadd into FeatureBaseDB:master Jul 3, 2019

jaffee added the changelog.added label Jul 25, 2019

codysoyland changed the title ~~Getting Started Update~~ Update "Getting Started" documentation Sep 17, 2019


		#### Create the Schema
		Pilosa supports curl (or any HTTP tool), Go, Java, and Python. In this project, we will walk you through how to use each one to best communicate with the Pilosa server.

		@@ -56,14 +55,20 @@ curl localhost:10101/schema
		{"indexes":null}


		##### Create the Environment

		In order to communicate with Pilosa through your Go code, you must have a "translator," which is go-pilosa. To install go-pilosa, open a terminal (one other than the one running Pilosa) and download the library in your `GOPATH` using:


		##### Create the Schema

		Before we can import data or run queries, we need to create our schema. Go-pilosa is implemented by importing `github.com/pilosa/go-pilosa` and its ability to read csv files is implemented by importing 'github.com/pilosa/go-pilosa/csv`. The first steps to creating the schema are creating a client which will communicate our schema to Pilosa, creating a schema which will contain our indexes and fields, and syncing with Pilosa. This is all done in the `StarTrace.go` file:

		```
		Note: This is the response you should receive once completing this project. It has also been formatted using `jq`.

Update "Getting Started" documentation #2028

Update "Getting Started" documentation #2028

Conversation

asvetlik commented Jun 28, 2019 • edited Loading

Overview

Pull request checklist

Code review checklist

asvetlik commented Jun 28, 2019

asvetlik commented Jun 28, 2019

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

alanbernstein Jun 28, 2019 • 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

alanbernstein Jun 28, 2019 • edited Loading

Choose a reason for hiding this comment

alanbernstein Jun 28, 2019 • 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

Choose a reason for hiding this comment

alanbernstein Jul 2, 2019 • 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

alanbernstein Jul 3, 2019 • edited Loading

Choose a reason for hiding this comment

alanbernstein Jul 3, 2019 • 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

alanbernstein left a comment

Choose a reason for hiding this comment

asvetlik commented Jun 28, 2019 •

edited

Loading

alanbernstein Jun 28, 2019 •

edited

Loading

alanbernstein Jun 28, 2019 •

edited

Loading

alanbernstein Jun 28, 2019 •

edited

Loading

alanbernstein Jul 2, 2019 •

edited

Loading

alanbernstein Jul 3, 2019 •

edited

Loading

alanbernstein Jul 3, 2019 •

edited

Loading