Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Super-fy the Installation doc #5408

Merged
merged 4 commits into from
Oct 31, 2024
+39 −45
Merged

Super-fy the Installation doc #5408

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5aa8616
Super-fy the Installation doc
philrz Oct 31, 2024
02db1fb
Update Homebrew description
philrz Oct 31, 2024
823590d
Remove excess newline
philrz Oct 31, 2024
13aea7d
PR feedback: Drop "to run"
philrz Oct 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions .goreleaser.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,7 @@ brews:
email: [email protected]
homepage: https://github.com/brimdata/super
description: |
SuperSQL or SuperPipe querying of common file formats
(CSV/JSON/Parquet/etc.) or SuperDB data lakes
An analytics database that puts JSON and relational tables on equal footing
install: |
bin.install "super"
checksum:
Expand Down
81 changes: 38 additions & 43 deletions docs/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,62 +5,57 @@ sidebar_label: Installation

# Installation

Several options for installing `zq` and/or `zed` are available:
* [HomeBrew](#homebrew) for Mac or Linux,
* [Binary Download](#binary-download), or
* [Build from Source](#building-from-source).
Several options for installing `super` are available:
* [Homebrew](#homebrew) for Mac or Linux,
* [Binary download](#binary-download), or
* [Build from source](#building-from-source).

To install the Zed Python client, see the
To install the SuperDB Python client, see the
[Python library documentation](libraries/python.md).

## Homebrew

On macOS and Linux, you can use [Homebrew](https://brew.sh/) to install `zq`:
On macOS and Linux, you can use [Homebrew](https://brew.sh/) to install `super`:

```bash
brew install brimdata/tap/zq
```

Similarly, to install `zed` for working with Zed lakes:
```bash
brew install brimdata/tap/zed
brew install brimdata/tap/super
```

Once installed, run a [quick test](#quick-tests).

## Binary Download

We offer pre-built binaries for macOS, Windows and Linux for both x86 and arm
architectures in the Zed [Github Release page](https://github.com/brimdata/super/releases).
We offer pre-built binaries for macOS, Windows and Linux for both amd64/x86 and arm
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I figured we might as well mention "amd64" explicitly since that's actually the architecture name that appears in the download artifacts on GitHub.

architectures in the super [GitHub Release page](https://github.com/brimdata/super/releases).

Each archive includes the build for `zq` and `zed`.
Once the `super` binary is unpacked from a downloaded package, run a [quick test](#quick-tests).

Once installed, run a [quick test](#quick-tests).
## Building From Source

## Building from source

If you have Go installed, you can easily build `zed` from source:
If you have Go installed, you can easily build `super` from source:

```bash
go install github.com/brimdata/super/cmd/{zed,zq}@latest
go install github.com/brimdata/super/cmd/super@latest
philrz marked this conversation as resolved.
Show resolved Hide resolved
```

This installs the `zed` and `zq` binaries in your `$GOPATH/bin`.

> If you don't have Go installed, download and install it from the
> [Go install page](https://golang.org/doc/install). Go 1.23 or later is
> required.
This installs the `super` binary in your `$GOPATH/bin`.

Once installed, run a [quick test](#quick-tests).

:::tip note
If you don't have Go installed, download and install it from the
[Go install page](https://golang.org/doc/install). Go 1.23 or later is
required.
:::

## Quick Tests

`zq` and `zed` are easy to test as they are completely self-contained
command-line tools and require no external dependendies to run.
`super` is easy to test as it's a completely self-contained
command-line tool and requires no external dependencies.

### Test zq
### Test `super`

To test `zq`, simply run this command in your shell:
To test `super`, simply run this command in your shell:
```mdtest-command
echo '"hello, world"' | super -z -
```
Expand All @@ -69,35 +64,35 @@ which should produce
"hello, world"
```

### Test zed
### Test `super db`

To test `zed`, we'll make a lake in `./scratch`, load data, and query it
To test `super db`, we'll make a SuperDB data lake in `./scratch`, load data, and query it
as follows:
```
export ZED_LAKE=./scratch
zed init
zed create Demo
echo '{s:"hello, world"}' | zed load -use Demo -
zed query "from Demo"
export SUPER_DB_LAKE=./scratch
super db init
super db create Demo
echo '{s:"hello, world"}' | super db load -use Demo -
super db query "from Demo"
```
which should display
```
{s:"hello, world"}
```
Alternatively, you can run a Zed lake service, load it with data using `zed load`,
Alternatively, you can run a lake service, load it with data using `super db load`,
and hit the API.

In one shell, run the server:
```
zed init -lake scratch
zed serve -lake scratch
super db init -lake scratch
super db serve -lake scratch
```
And in another shell, run the client:
```
zed create Demo
zed use Demo
echo '{s:"hello, world"}' | zed load -
zed query "from Demo"
super db create Demo
super db use Demo
echo '{s:"hello, world"}' | super db load -
super db query "from Demo"
```
which should also display
```
Expand Down