Skip to content

DOC-2921 support sampling local file [4.3] #872

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

Open
wants to merge 2 commits into
base: 4.3.0-dev
Choose a base branch
from
Open

DOC-2921 support sampling local file [4.3] #872

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0850a81
DOC-2921 support sampling local file [4.3]
AyeshaFirdausTG Sep 30, 2025
e307534
DOC-2921 Support sampling local-file-[4.3]
AyeshaFirdausTG Oct 6, 2025
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
133 changes: 131 additions & 2 deletions modules/API/pages/gsql-endpoints.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2757,11 +2757,11 @@ Sample Response::
====

'''
=== get the sample data of S3 file.uris or local files
=== get sample data from an S3 object

`POST /gsql/v1/sample-data`

Get the sample data of S3 file.uris or local files.
Get the first N lines from an S3 object

==== Parameters:

Expand Down Expand Up @@ -2884,6 +2884,80 @@ Sample Response::
--
====

=== Get the sample data from a local file
`POST /gsql/v1/sample-data`

Get the first N of lines of data from a local file, as a sample

==== Parameters:

[%autowidth]
|===
| Name | Required | Description

| `path`
| yes
| Local file URI, starts with `file://`

| `size`
| no
| Number of lines to return (default: 10).
|===

==== Example

[,tabs]
====
Sample Request::
+
--
[source,bash]
----
curl -u tigergraph:tigergraph 'http://<tigergraph-host>:14240/gsql/v1/sample-data' \
-d '{
"path": "file:///path/to/local/filename",
"size": 3
}'

----
--
Sample Response::
+
--
[source.wrap,console]
----
{
"error": false,
"message": "",
"results": {
"data": [
{
"user_id": 1001,
"age": 33,
"state": "fl"

},
{
"user_id": 1002,
"age": 41,
"state": "ca"
},
{
"user_id": 1003,
"age": 26,
"state": "az"
}
],
"header": [],
"json": true
}
}
----
--
====



'''
=== get all buckets of given S3 data source

Expand Down Expand Up @@ -2915,6 +2989,61 @@ Sample Response::
----
--
====
=== Get the sample data of local files
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
=== Get the sample data of local files
=== Get sample data from a local file

"The" is incorrect, because there is not just one possible or correct sample of data.
The data is coming from only one file, not "files"

`POST /gsql/v1/sample-data`

Get the sample data of local files
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
Get the sample data of local files
Get the first N of lines of data from a local file, as a sample

"Sample" is a generic, non-specific concept. To a statistician, "sample" actually suggests that the data is chosen randomly. But I assume our selection is not random. We are selecting the first N lines. Is that correct?
We should provide a clearly explanation of how the data is chosen.


==== Parameters:

[%autowidth]
|===
| Name | Required | Description

| `path`
| yes
| local file path (`file://`).

| `size`
| no
| Number of lines to return (default: 10).
|===

==== Example

[,tabs]
====
Sample Request::
+
--
[source,bash]
----
curl -u tigergraph:tigergraph 'http://<tigergraph-host>:14240/gsql/v1/sample-data' \
-d '{
"path": "file:///path/to/local/filename",
"size": 10
}'

----
--
Sample Response::
+
--
[source.wrap,console]
----
{
"error": false,
"message": "Sample data loaded successfully",
"results": {
"file": "file:///path/to/local/filename",
"loadedRecords": 10
}
}
----
--
====



'''
=== get all files and directories under given S3 bucket path
Expand Down