Merge pull request #34 from axiomhq/arne/dx-369-add-manual-client-setup-to-axiom-rs-in

Add manual client setup to README, lift query & ingest to top-level and more

Author: bahlo

.github/workflows/ci.yaml

@@ -1,6 +1,6 @@
 name: CI
 
-on: 
+on:
   pull_request:
     branches:
       - main
@@ -81,6 +81,25 @@ jobs:
         with:
           command: test
           args: ${{ matrix.flags }} -- --test-threads 1
+  build_examples:
+    name: Build examples
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+      - name: Install rust
+        uses: actions-rs/toolchain@v1
+      - name: Run cargo build --examples
+        uses: actions-rs/cargo@v1
+        with:
+          command: build
+          args: --examples
   publish_on_crates_io:
     name: Publish on crates.io
     runs-on: ubuntu-latest
@@ -89,6 +108,7 @@ jobs:
       - rust_fmt_check
       - clippy_check
       - test
+      - build_examples
     steps:
       - uses: actions/checkout@v3
       - uses: actions-rs/toolchain@v1

Cargo.toml

@@ -34,13 +34,15 @@ tracing = { version = "0.1" }
 tokio-stream = "0.1"
 
 [dev-dependencies]
-tokio = { version = "1", features = ["rt", "macros"] }
+tokio = { version = "1", features = ["full"] }
 async-std = { version = "1", features = ["attributes"] }
 serde_test = "1"
 test-context = "0.1"
 async-trait = "0.1"
 futures-util = "0.3"
 httpmock = "0.6"
+structopt = "0.3"
+tracing-subscriber = { version = "0.3", features = ["ansi", "env-filter"] }
 
 [features]
 default = ["tokio", "default-tls"]

README.md

@@ -18,7 +18,7 @@
 
 For more information check out the [official documentation](https://axiom.co/docs).
 
-## Usage
+## Quickstart
 
 Add the following to your Cargo.toml:
 
@@ -27,9 +27,13 @@ Add the following to your Cargo.toml:
 axiom-rs = "0.6"
 ```
 
-If you use the [Axiom CLI](https://github.com/axiomhq/cli), run `eval $(axiom config export -f)` to configure your environment variables.
+If you use the [Axiom CLI](https://github.com/axiomhq/cli), run
+`eval $(axiom config export -f)` to configure your environment variables.
 
-Otherwise create a personal token in [the Axiom settings](https://cloud.axiom.co/settings/profile) and export it as `AXIOM_TOKEN`. Set `AXIOM_ORG_ID` to the organization ID from the settings page of the organization you want to access.
+Otherwise create a personal token in
+[the Axiom settings](https://cloud.axiom.co/settings/profile) and make note of
+the organization ID from the settings page of the organization you want to
+access.
 
 Create and use a client like this:
 
@@ -39,16 +43,29 @@ use serde_json::json;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Build your client by providing a personal token and an org id:
+    let client = Client::builder()
+        .with_token("my-token")
+        .with_org_id("my-org")
+        .build()?;
+
+    // Alternatively you autoconfigure the client from the environment variables
+    // AXIOM_TOKEN and AXIOM_ORG_ID:
     let client = Client::new()?;
 
     client.datasets.create("my-dataset", "").await?;
 
-    client.datasets.ingest("my-dataset", vec![json!({
-        "foo": "bar",
-    })]).await?;
+    client
+        .ingest(
+            "my-dataset",
+            vec![json!({
+                "foo": "bar",
+            })],
+        )
+        .await?;
 
-    let res = client.datasets
-        .apl_query(r#"['my-dataset'] | where foo == "bar" | limit 100"#, None)
+    let res = client
+        .query(r#"['my-dataset'] | where foo == "bar" | limit 100"#, None)
         .await?;
     println!("{:?}", res);
 

examples/Cargo.toml

@@ -1,24 +1,30 @@
-# cli
+# Examples
 
-This example implements a very basic CLI for [Axiom](https://axiom.co).
-
-> **Warning**: This is meant to show some examples on how to call the various methods.
-> Please don't actually use this, we have an 
-> [official CLI](https://github.com/axiomhq/cli).
+There's two examples: cli and ingest-hn.
 
 ## Prerequisites
 
-You'll need an account at [Axiom](https://cloud.axiom.co) and a personal token.
+You'll need an account at [Axiom](https://cloud.axiom.co), a dataset and an API
+token that can ingest into that dataset.
+
+## cli
+
+This example implements a very basic CLI for [Axiom](https://axiom.co).
+
+> **Warning**: This is meant to show some examples on how to call the various
+> methods.
+> Please don't actually use this, we have an
+> [official CLI](https://github.com/axiomhq/cli).
 
-## Start the example
+### Start the example
 
 ```sh
 export AXIOM_TOKEN=<your personal token>
 export AXIOM_ORG_ID=<your axiom org id>
 cargo run
 ```
 
-## Usage
+### Usage
 
 ```
 $ cd examples/cli && cargo run
@@ -37,5 +43,17 @@ SUBCOMMANDS:
     users       Work with users
 ```
 
-You can run something like `cargo run -- datasets --help` to get more 
-information about subcommands and available flags.
+You can run something like `cargo run -- datasets --help` to get more
+information about subcommands and available flags.
+
+## ingest-hn
+
+This example ingests all HN posts into an Axiom dataset.
+
+### Start the example
+
+```sh
+export DATASET_NAME=<your dataset name>
+export AXIOM_TOKEN=<your api token>
+cargo run
+```

examples/cli/README.md renamed to examples/README.md

@@ -100,13 +100,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                 let mut buf = Vec::new();
                 stdin().read_to_end(&mut buf).await?;
                 let ingest_status = client
-                    .datasets
-                    .ingest_raw(&name, buf, content_type, content_encoding)
+                    .ingest_bytes(&name, buf, content_type, content_encoding)
                     .await?;
                 println!("{:?}", ingest_status);
             }
             Datasets::Query { apl } => {
-                let result = client.datasets.apl_query(apl, None).await?;
+                let result = client.query(apl, None).await?;
                 println!("{:?}", result);
             }
         },

examples/cli/src/main.rs renamed to examples/cli.rs

@@ -33,7 +33,6 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         })
         .buffered(100);
     Client::new()?
-        .datasets
         .try_ingest_stream(dataset_name, stream)
         .await?;
     Ok(())