Skip to content

Commit c6e512d

Browse files
lovasoalovasoa
committed
update docs
1 parent 8a7682f commit c6e512d

File tree

2 files changed

+71
-20
lines changed

2 files changed

+71
-20
lines changed

‎examples/official-site/sqlpage/migrations/11_json.sql

+44-12
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,22 @@ INSERT INTO
33
VALUES
44
(
55
'json',
6-
'For advanced users, allows you to easily build an API over your database.
7-
The json component responds to the current HTTP request with a JSON object.
8-
This component must appear at the top of your SQL file, before any other data has been sent to the browser.',
6+
'Converts SQL query results into the JSON machine-readable data format. Ideal to quickly build APIs for interfacing with external systems.
7+
8+
**JSON** is a widely used data format for programmatic data exchange.
9+
For example, you can use it to integrate with web services written in different languages,
10+
with mobile or desktop apps, or with [custom client-side components](/custom_components.sql) inside your SQLPage app.
11+
12+
Use it when your application needs to expose data to external systems.
13+
If you only need to render standard web pages,
14+
and do not need other software to access your data,
15+
you can ignore this component.
16+
17+
This component **must appear at the top of your SQL file**, before any other data has been sent to the browser.
18+
An HTTP response can have only a single datatype, and it must be declared in the headers.
19+
So if you have already called the `shell` component, or another traditional HTML component,
20+
you cannot use this component in the same file.
21+
',
922
'code',
1023
'0.9.0'
1124
);
@@ -32,7 +45,10 @@ VALUES
3245
(
3346
'json',
3447
'type',
35-
'The type of the JSON payload to send. Defaults to "array" (each query result is rendered as a JSON object in the array). Other possible values are "jsonlines" (each query result is rendered as a JSON object in a new line, without a top-level array) and "sse" (each query result is rendered as a JSON object in a new line, prefixed by "data: ", which allows you to read the results as server-sent events in real-time from javascript).',
48+
'The type of the JSON payload to send: "array", "jsonlines", or "sse".
49+
In "array" mode, each query result is rendered as a JSON object in a single top-level array.
50+
In "jsonlines" mode, results are rendered as JSON objects in separate lines, without a top-level array.
51+
In "sse" mode, results are rendered as JSON objects in separate lines, prefixed by "data: ", which allows you to read the results as server-sent events in real-time from javascript.',
3652
'TEXT',
3753
TRUE,
3854
TRUE
@@ -45,7 +61,14 @@ VALUES
4561
(
4662
'json',
4763
'
48-
## Send query results as a JSON array
64+
## Send query results as a single JSON array: `''array'' as type`
65+
66+
The default `array` mode sends the query results as a single JSON array.
67+
68+
If a query returns an error, the array will contain an object with an `error` property.
69+
70+
If multiple queries are executed, all query results will be concatenated into a single array
71+
of heterogeneous objects.
4972
5073
### SQL
5174
@@ -67,10 +90,21 @@ select * from users;
6790
(
6891
'json',
6992
'
70-
## Send a single JSON object
93+
## Send a single JSON object: `''jsonlines'' as type`
94+
95+
In `jsonlines` mode, each query result is rendered as a JSON object in a separate line,
96+
without a top-level array.
97+
98+
If there is a single query result, the response will be a valid JSON object.
99+
If there are multiple query results, you will need to parse each line of the response as a separate JSON object.
100+
101+
If a query returns an error, the response will be a JSON object with an `error` property.
71102
72103
### SQL
73104
105+
The following SQL creates an API endpoint that takes a `user_id` URL parameter
106+
and returns a single JSON object containing the user''s details, with one json object key per column in the `users` table.
107+
74108
```sql
75109
select ''json'' AS component, ''jsonlines'' AS type;
76110
select * from users where id = $user_id LIMIT 1;
@@ -91,7 +125,7 @@ select * from users where id = $user_id LIMIT 1;
91125
(
92126
'json',
93127
'
94-
## Create a complex API endpoint
128+
## Create a complex API endpoint: the `''contents''` property
95129
96130
You can create an API endpoint that will return a JSON value in any format you want,
97131
to implement a complex API.
@@ -138,12 +172,12 @@ you can use
138172
(
139173
'json',
140174
'
141-
## Access query results in real-time with server-sent events
175+
## Access query results in real-time with server-sent events: `''sse'' as type`
142176
143177
Using server-sent events, you can stream large query results to the client in real-time,
144178
row by row.
145179
146-
This allows building sophisticated dynamic applications that will start processing and displaying
180+
This allows building sophisticated dynamic web applications that will start processing and displaying
147181
the first rows of data in the browser while the database server is still processing the end of the query.
148182
149183
### SQL
@@ -161,9 +195,7 @@ eventSource.onmessage = function (event) {
161195
const user = JSON.parse(event.data);
162196
console.log(user.username);
163197
}
164-
eventSource.onerror = function () {
165-
eventSource.close(); // do not reconnect after reading all the data
166-
}
198+
eventSource.onerror = () => eventSource.close(); // do not reconnect after reading all the data
167199
```
168200
'
169201
);

‎examples/official-site/sqlpage/migrations/48_status_code.sql

+27-8
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,31 @@ INSERT INTO
44
VALUES
55
(
66
'status_code',
7-
'A simple component to set the HTTP status code for the response. This can be used to indicate the result of the request, such as 200 for success, 404 for not found, or 500 for server error.
7+
'Sets the HTTP response code for the current page.
88
9-
The status code should be set according to the HTTP standard status codes.
9+
This is an advanced technical component.
10+
You typically need it when building internet-facing APIs and websites,
11+
but you may not need it for simple internal applications.
1012
11-
This component should be used when you need to explicitly set the status code of the HTTP response.
12-
',
13+
- Indicating operation results when using [SQLPage as an API](?component=json)
14+
- `200`: *OK*, for successful operations
15+
- `201`: *Created*, for successful record insertion
16+
- `404`: *Not Found*, for missing resources
17+
- `500`: *Internal Server Error*, for failed operations
18+
- Handling data validation errors
19+
- `400`: *Bad Request*, for invalid data
20+
- Enforcing access controls
21+
- `403`: *Forbidden*, for unauthorized access
22+
- `401`: *Unauthorized*, for unauthenticated access
23+
- Tracking system health
24+
- `500`: *Internal Server Error*, for failed operations
25+
26+
For search engine optimization:
27+
- Use `404` for deleted content to remove outdated URLs from search engines
28+
- For redirection from one page to another, use
29+
- `301` (moved permanently), or
30+
- `302` (moved temporarily)
31+
- Use `503` during maintenance',
1332
'error-404'
1433
);
1534

@@ -27,20 +46,20 @@ VALUES
2746
(
2847
'status_code',
2948
'status',
30-
'The HTTP status code to be set for the response. This should be an integer value representing a valid HTTP status code.',
49+
'HTTP status code (e.g., 200 OK, 401 Unauthorized, 409 Conflict)',
3150
'INTEGER',
3251
TRUE,
3352
FALSE
3453
);
3554

36-
3755
INSERT INTO example (component, description)
3856
VALUES (
3957
'status_code',
40-
'Set the HTTP status code to 404, indicating that the requested resource was not found.
58+
'
59+
Set the HTTP status code to 404, indicating that the requested resource was not found.
4160
Useful in combination with [`404.sql` files](/your-first-sql-website/custom_urls.sql):
4261
4362
```sql
44-
select ''status_code'' as component, 404 as status;
63+
SELECT ''status_code'' as component, 404 as status;
4564
```
4665
');

0 commit comments

Comments
 (0)