Skip to content

Commit acbe8ab

Browse files
lukekimlukekim
authored
Improve documentation formatting for clarity and consistency (#1389)
* Refine documentation across various sections for clarity and consistency - Updated descriptions in datasets, models, runtime, and views documentation to enhance readability and precision. - Improved explanations regarding retry mechanisms and refresh attempts in acceleration settings. - Clarified the purpose and functionality of the `WITH` clause in SQL documentation. - Enhanced troubleshooting guidance with detailed common issues and solutions for dataset loading, query performance, and AI chat results. - Revised use case descriptions for agentic apps, edge AI, federated MCP server, object-store AI engine, and more to improve clarity and impact. - Streamlined language throughout the documentation to ensure consistency and better user understanding. * Improve documentation formatting for clarity and consistency across multiple sections * Apply suggestion from @lukekim * Update documentation links for consistency and clarity across multiple sections
1 parent c4c9d8a commit acbe8ab

124 files changed

Lines changed: 1187 additions & 304 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎website/docs/api/HTTP/patch-dataset-acceleration.api.mdx‎

Lines changed: 97 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,125 @@
11
---
22
id: patch-dataset-acceleration
3-
title: "Update Refresh SQL"
3+
title: 'Update Refresh SQL'
44
description: "Update the refresh SQL for a dataset's acceleration."
5-
sidebar_label: "Update Refresh SQL"
5+
sidebar_label: 'Update Refresh SQL'
66
hide_title: true
77
hide_table_of_contents: true
88
api: eJztVt9v2zYQ/leIe+kWKLJddMCmhwJZmqEDUmxzU/QhNRxaPFtsKVIhT3YMQf/7cJTkH7EXbNjj5hdL4vH48fvuPrIBkqsA2T28kyQDUoBZAgpD7nVF2lnI4FOlJKGgAoXHpcdQiI9/3Iql80IK1U17FYTMczToJc9Kv9gv9q7QQaBVldOWhDTGbUKcVXNCbVcx5UOfcx4ezYOopJclEvoX0wtJwteWdIkpr4MiL6RdodBBXFwQlpXz0m8vLoS0Smy0McLjGj0Jct2iodI5Vk6l29I8CIVLbfWQmQMsPu2WEB4DSU8pJOCqHsKvCjKoJOXFvMc4P0QICey2wvQ2YGWJkHV/CWjbTS/gOdu8Gw4SbhmR9NkZeeQNGYbHx1p7VJCRrzGBkBdYSsgaoG3FywTy2q6gbWddMAb62aktR5wu1+VVUdVAkrBES1GAAwCvwqA+A8idJbTE+WRVGZ3HXY++Bk7anOJxi6+YE7PimULSGHj0QPt98P2APgFbG3NakMc464BqB3aAKN7hUtaGwk7xozILFeZ6qVEJbePwrh6gbRMgTYZRXx0oOu1YhDYBfJJlxQHPNgAfb25vru/Ehfhl+tsHgVTMPeZoab4wLv8WxOf3N9MbEV/mti4X6MVbMRmPoeVVj0WNH0LlbOioej0en1fvsCc3MuzUDHWeYwjL2phtyrDfjN+cz7BnYyg2zmMd10Bt1b+Re7+neygxBLlC1vO4CoaBk/I91xt9sOhGFoONeAy1oaFp/CDWgZgfuonTntRnQu4wDEZ4Rr49I20U7IdzklxZoS2ht9KIgH6NXqD3zguX57X3qMSm0AaPTfBAw/8Y231biaXUBlUq/jF9B9SlUZc2gRKpcDuDjl5MBWQwWk9GfYmHUcMu246euXa3ZmfZteemLoiqbDQyLpemcIGyH8c/jU/IuuVhoXCNxlXRl7pMqbh2dqlXtUex0VSIh8tLzviQAntzwLz2mrZxPVnp+Tfk5xmPsd7TvXff/JXrDF7Pp8rSRV17EfoD7Kyy0fGU2IcYnSMrle3OqqtK5gVevk55u1qhJXYJfzzSJsCEdYkn6WSSji9rG0guTFS9coFKaQ/S9veJ6VHNHwFs9i3w/+3j4PbR9yvhE40qI7VlgmOVNn2J38N6wmwOl7kEsv7GcVTnswS4lDm+aRYy4Cdv2pY/P9boYwUmsJZeRxW5NpUO/KwgW0oT8AXBvpv2LvS9+Ft3mbOb6j9KuwUGYmp+gwRie3SF1M7aBAqUiivyvumHrjscl3ecYD/1xEfbZJjBh3xFL8bODizl96u76/eQwKK/TpVOxVaTGzZguelwukhMd8fhbw0YaVd153ldUv79CfhKCg4=
9-
sidebar_class_name: "patch api-method"
9+
sidebar_class_name: 'patch api-method'
1010
info_path: docs/api/HTTP/runtime
1111
custom_edit_url: null
1212
proxy: http://localhost:8090
1313
---
1414

15-
import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
16-
import ParamsDetails from "@theme/ParamsDetails";
17-
import RequestSchema from "@theme/RequestSchema";
18-
import StatusCodes from "@theme/StatusCodes";
19-
import OperationTabs from "@theme/OperationTabs";
20-
import TabItem from "@theme/TabItem";
21-
import Heading from "@theme/Heading";
15+
import MethodEndpoint from '@theme/ApiExplorer/MethodEndpoint'
16+
import ParamsDetails from '@theme/ParamsDetails'
17+
import RequestSchema from '@theme/RequestSchema'
18+
import StatusCodes from '@theme/StatusCodes'
19+
import OperationTabs from '@theme/OperationTabs'
20+
import TabItem from '@theme/TabItem'
21+
import Heading from '@theme/Heading'
2222

23-
<Heading
24-
as={"h1"}
25-
className={"openapi__heading"}
26-
children={"Update Refresh SQL"}
27-
>
28-
</Heading>
23+
<Heading as={'h1'} className={'openapi__heading'} children={'Update Refresh SQL'}></Heading>
2924

3025
<MethodEndpoint
31-
method={"patch"}
32-
path={"/v1/datasets/{name}/acceleration"}
33-
context={"endpoint"}
34-
>
35-
36-
</MethodEndpoint>
37-
38-
26+
method={'patch'}
27+
path={'/v1/datasets/{name}/acceleration'}
28+
context={'endpoint'}
29+
></MethodEndpoint>
3930

4031
Update the refresh SQL for a dataset's acceleration.
4132

42-
This endpoint allows for updating the `refresh_sql` parameter for a dataset's acceleration at runtime.
33+
This endpoint updates the `refresh_sql` parameter for a dataset's acceleration at runtime.
4334
The change is **temporary** and will revert to the `spicepod.yml` definition at the next runtime restart.
4435

4536
<Heading
46-
id={"request"}
47-
as={"h2"}
48-
className={"openapi-tabs__heading"}
49-
children={"Request"}
50-
>
51-
</Heading>
37+
id={'request'}
38+
as={'h2'}
39+
className={'openapi-tabs__heading'}
40+
children={'Request'}
41+
></Heading>
5242

5343
<ParamsDetails
54-
parameters={[{"name":"name","in":"path","description":"The name of the dataset to update.","required":true,"schema":{"type":"string"}}]}
55-
>
56-
57-
</ParamsDetails>
44+
parameters={[
45+
{
46+
name: 'name',
47+
in: 'path',
48+
description: 'The name of the dataset to update.',
49+
required: true,
50+
schema: { type: 'string' }
51+
}
52+
]}
53+
></ParamsDetails>
5854

5955
<RequestSchema
60-
title={"Body"}
61-
body={{"description":"The updated SQL statement for the dataset's refresh.","content":{"application/json":{"schema":{"type":"object","properties":{"refresh_sql":{"type":["string","null"],"description":"SQL statement used for the refresh. Defaults to the `refresh_sql` specified in the spicepod."}},"title":"AccelerationRequest"},"example":{"refresh_sql":"SELECT * FROM eth_recent_blocks WHERE block_number > 100"}}},"required":true}}
62-
>
63-
64-
</RequestSchema>
56+
title={'Body'}
57+
body={{
58+
description: "The updated SQL statement for the dataset's refresh.",
59+
content: {
60+
'application/json': {
61+
schema: {
62+
type: 'object',
63+
properties: {
64+
refresh_sql: {
65+
type: ['string', 'null'],
66+
description:
67+
'SQL statement used for the refresh. Defaults to the `refresh_sql` specified in the spicepod.'
68+
}
69+
},
70+
title: 'AccelerationRequest'
71+
},
72+
example: { refresh_sql: 'SELECT * FROM eth_recent_blocks WHERE block_number > 100' }
73+
}
74+
},
75+
required: true
76+
}}
77+
></RequestSchema>
6578

6679
<StatusCodes
6780
id={undefined}
6881
label={undefined}
69-
responses={{"200":{"description":"The refresh SQL was updated successfully."},"404":{"description":"The specified dataset was not found","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"The message describing the result of the request"}},"title":"MessageResponse"},"example":{"message":"Dataset eth_recent_blocks not found"}}}},"500":{"description":"An internal server error occurred while updating the refresh SQL","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"The message describing the result of the request"}},"title":"MessageResponse"},"example":{"message":"Request failed. An internal server error occurred while updating refresh SQL."}}}}}}
70-
>
71-
72-
</StatusCodes>
73-
74-
75-
82+
responses={{
83+
'200': { description: 'The refresh SQL was updated successfully.' },
84+
'404': {
85+
description: 'The specified dataset was not found',
86+
content: {
87+
'application/json': {
88+
schema: {
89+
type: 'object',
90+
required: ['message'],
91+
properties: {
92+
message: {
93+
type: 'string',
94+
description: 'The message describing the result of the request'
95+
}
96+
},
97+
title: 'MessageResponse'
98+
},
99+
example: { message: 'Dataset eth_recent_blocks not found' }
100+
}
101+
}
102+
},
103+
'500': {
104+
description: 'An internal server error occurred while updating the refresh SQL',
105+
content: {
106+
'application/json': {
107+
schema: {
108+
type: 'object',
109+
required: ['message'],
110+
properties: {
111+
message: {
112+
type: 'string',
113+
description: 'The message describing the result of the request'
114+
}
115+
},
116+
title: 'MessageResponse'
117+
},
118+
example: {
119+
message: 'Request failed. An internal server error occurred while updating refresh SQL.'
120+
}
121+
}
122+
}
123+
}
124+
}}
125+
></StatusCodes>

0 commit comments

Comments
 (0)