InfluxDB ILP: Use an unambiguous local-file form

[amotl]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check existing examples/tests for the accepted ILP file input form.
rg -nP --type=py -C2 'ctk load .*\.lp|file://.*\.lp|influxdb-export\.lp|observations\.lp'

Repository: crate/cratedb-toolkit

Length of output: 493

---

🏁 Script executed:

#!/bin/bash
# Find the ctk load command implementation
fd -e py | xargs grep -l "def load" | head -20

Repository: crate/cratedb-toolkit

Length of output: 472

---

🏁 Script executed:

#!/bin/bash
# Search for URI parsing logic and file:// handling in the codebase
rg -nP "file://" -A 3 -B 3 --type=py

Repository: crate/cratedb-toolkit

Length of output: 1245

---

🏁 Script executed:

#!/bin/bash
# Check if there's any documentation or usage examples for ctk load command
rg -nP "ctk load|file://" doc/ --type=md | head -30

Repository: crate/cratedb-toolkit

Length of output: 1667

---

🏁 Script executed:

#!/bin/bash
# Find the ctk load command implementation
rg -nP "def load|@.*\.command\(.*load" --type=py -A 5 | head -60

Repository: crate/cratedb-toolkit

Length of output: 3880

---

🏁 Script executed:

#!/bin/bash
# Search for router/URI handling in the codebase
fd -e py -path "*/io/*" | xargs grep -l "class.*Router\|urlparse\|from.*uri" | head -20

Repository: crate/cratedb-toolkit

Length of output: 233

---

🏁 Script executed:

#!/bin/bash
# Look at the router.py file which likely handles URI parsing
head -100 cratedb_toolkit/io/router.py

Repository: crate/cratedb-toolkit

Length of output: 3399

---

🏁 Script executed:

#!/bin/bash
# Find all uses of file:// in the codebase
rg "file://" -n --type=py --type=md

Repository: crate/cratedb-toolkit

Length of output: 1039

---

🏁 Script executed:

#!/bin/bash
# Look at how InputOutputResource and URL are used with file paths
rg -n "InputOutputResource|class.*Resource" --type=py -A 5 | head -80

Repository: crate/cratedb-toolkit

Length of output: 4715

---

🏁 Script executed:

#!/bin/bash
# Check what boltons.urlutils.URL does with file:// paths
python3 << 'EOF'
try:
    from boltons.urlutils import URL
    # Test different file URI forms
    test_urls = [
        "file://observations.lp",
        "file:///observations.lp",
        "file:///path/to/observations.lp",
        "observations.lp",
    ]
    for url_str in test_urls:
        try:
            url = URL(url_str)
            print(f"URL: {url_str}")
            print(f"  scheme: {url.scheme}")
            print(f"  host: {url.host}")
            print(f"  path: {url.path}")
            print()
        except Exception as e:
            print(f"URL: {url_str} - ERROR: {e}\n")
except ImportError:
    print("boltons not available, need to install")
EOF

Repository: crate/cratedb-toolkit

Length of output: 381

---

Use an unambiguous local-file form for ILP examples.

Lines 16 and 72 use file://observations.lp and file://influxdb-export.lp, which parse ambiguously with boltons.urlutils.URL. The form file://name treats name as the hostname, not the file path. This would cause the loader to fail. Use either a plain relative path (observations.lp) or the standard three-slash file URI form (file:///absolute/path/observations.lp).

Suggested doc fix

-- Load from InfluxDB line protocol: `ctk load file://observations.lp`
+- Load from InfluxDB line protocol: `ctk load observations.lp`

-ctk load "file://influxdb-export.lp"
+ctk load "influxdb-export.lp"

Also applies to: 72-72

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@doc/io/database/influxdb/index.md` at line 16, The ILP example URIs
`file://observations.lp` and `file://influxdb-export.lp` are ambiguous (they are
parsed as hostnames); replace them with an unambiguous local-file form — use a
plain relative path like `observations.lp` (preferred for examples) or a full
three-slash file URI like `file:///absolute/path/observations.lp` — update the
two occurrences of those literals in the markdown to one of these forms so the
loader won't misinterpret them.

Originally posted by @coderabbitai[bot] in #706 (comment)

[amotl]

Lines 16 and 72 use file://observations.lp and file://influxdb-export.lp, which parse ambiguously with boltons.urlutils.URL. The form file://name treats name as the hostname, not the file path. This would cause the loader to fail. Use either a plain relative path (observations.lp) or the standard three-slash file URI form (file:///absolute/path/observations.lp).

@coderabbitai: I think the influxio package compensates for that ambiguity by using relevant helper code so that no error will be raised, and so that the machinery also supports addressing files relatively for better DWIM, even when using the URL-style file:// notation. Please verify that.

@hampsterx: I don't have any objections to streamline the documentation accordingly with GH-720 to support resources on the local filesytem more elegantly than before, thank you.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

Let me verify the referenced influxio helper code.

---

🏁 Script executed:

#!/bin/bash
# Fetch the influxio helper code that handles file:// ambiguity
curl -s "https://raw.githubusercontent.com/daq-tools/influxio/v0.7.3/influxio/util/common.py" | sed -n '60,90p'

Length of output: 511

---

@amotl, you are correct. The influxio helper code at influxio/util/common.py intentionally compensates for this:

def url_fullpath(url: URL):
    fullpath = url.host or ""
    if fullpath == "-":
        return fullpath
    fullpath += url.path or ""
    return fullpath.rstrip("/")

When file://observations.lp is parsed by boltons.urlutils.URL, it yields host="observations.lp" and path="". The url_fullpath helper then reassembles both components, returning the correct local path "observations.lp". This is deliberate DWIM behaviour — my original concern about the loader failing was mistaken. I apologise for the noise.

---

✏️ Learnings added

Learnt from: amotl
URL: https://github.com/crate/cratedb-toolkit/issues/707

Timestamp: 2026-03-24T11:21:02.367Z
Learning: In the `cratedb-toolkit` project, the `influxio` package (used for InfluxDB line protocol loading) intentionally compensates for the `file://name` URI ambiguity (where `boltons.urlutils.URL` parses `name` as the hostname). The helper `url_fullpath()` in `influxio/util/common.py` concatenates `url.host + url.path`, so `file://observations.lp` correctly resolves to the local file `observations.lp`. Do not flag `file://` two-slash forms in ILP documentation as broken — they are valid and supported by design.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

---

🧠 Learnings used

Learnt from: amotl
Repo: crate/cratedb-toolkit PR: 81
File: cratedb_toolkit/cfr/marimo.py:53-54
Timestamp: 2025-05-02T11:43:42.639Z
Learning: The submodules within `cratedb_toolkit/io` employ a different naming scheme than other parts of the codebase and retain their own conventions (e.g., may continue using `cratedb_sqlalchemy_url` instead of `sqlalchemy_url`).