Skip to content

Commit 8b9cfb6

Browse files
cmccarthy1cmccarthy1
authored
Merge pull request #32 from KxSystems/pykx-252
MR for 2.5.2 feature additions
2 parents 57a42b4 + 875e047 commit 8b9cfb6

File tree

16 files changed

+403
-123
lines changed

16 files changed

+403
-123
lines changed

‎docs/getting-started/q_magic_command.ipynb

Lines changed: 132 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,31 @@
11
{
22
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "5c1e9b66",
6+
"metadata": {},
7+
"source": [
8+
"# Jupyter q Magic Command Notebook\n",
9+
"\n",
10+
"_The purpose of this notebook is to exemplify how to use the q Magic command in a Jupyter notebook._\n",
11+
"\n",
12+
"\n",
13+
"The Jupyter q magic command in PyKX allows you to execute q code within a Jupyter notebook. It provides seamless integration with the q programming language.\n",
14+
"\n",
15+
"This example Notebook has the following sections:\n",
16+
"\n",
17+
"1. [Import PyKX](#1-import-pykx)\n",
18+
"1. [Create the external q process](#2-create-the-external-q-process)\n",
19+
"1. [Execute against Embedded q](#3-execute-against-embedded-q)\n",
20+
"1. [SQL interface](#4-sql-interface)\n",
21+
"1. [q namespaces](#5-q-namespaces)\n",
22+
"1. [(Advanced) q over IPC](#6-advanced-q-over-ipc)"
23+
]
24+
},
325
{
426
"cell_type": "code",
527
"execution_count": null,
28+
"id": "2f25482a",
629
"metadata": {
730
"tags": [
831
"hide_code"
@@ -15,6 +38,16 @@
1538
"os.environ['PYKX_Q_LOADED_MARKER'] = '' # Only used here for running Notebook under mkdocs-jupyter during document generation."
1639
]
1740
},
41+
{
42+
"cell_type": "markdown",
43+
"id": "688b9ed0",
44+
"metadata": {},
45+
"source": [
46+
"## 1. Import PyKX\n",
47+
"\n",
48+
"To run this example, first import the PyKX library:"
49+
]
50+
},
1851
{
1952
"cell_type": "code",
2053
"execution_count": null,
@@ -30,12 +63,9 @@
3063
"id": "9c520c21",
3164
"metadata": {},
3265
"source": [
33-
"#### Create the external q process\n",
34-
"To run this example, the Python code in the following cell will do the equivalent to executing the following in a terminal:\n",
66+
"## 2. Create the external q process\n",
3567
"\n",
36-
"```\n",
37-
"$ q -p 5001\n",
38-
"```"
68+
"You can run an external q process by using the following Python code:"
3969
]
4070
},
4171
{
@@ -58,13 +88,27 @@
5888
" raise kx.QError('Unable to create q process on port 5000')"
5989
]
6090
},
91+
{
92+
"cell_type": "markdown",
93+
"id": "1b318ba2",
94+
"metadata": {},
95+
"source": [
96+
"\n",
97+
"Or execute this command in a terminal:\n",
98+
"\n",
99+
"```sh\n",
100+
"$ q -p 5000\n",
101+
"```\n"
102+
]
103+
},
61104
{
62105
"cell_type": "markdown",
63106
"id": "bc7219fb",
64107
"metadata": {},
65108
"source": [
66-
"#### Executing against Embedded q\n",
67-
"A cell beginning with `%%q` will execute q within `PyKX`'s `EmbeddedQ` module."
109+
"## 3. Execute against Embedded q\n",
110+
"\n",
111+
"To execute q code within PyKX's `EmbeddedQ` module, type `%%q` at the beginning of the cell:"
68112
]
69113
},
70114
{
@@ -83,23 +127,18 @@
83127
"id": "89ec26e4",
84128
"metadata": {},
85129
"source": [
86-
"#### Execution options\n",
87-
"\n",
88-
"Execution options can also be included after `%%q`.\n",
130+
"After `%%q` you can further add two execution options:\n",
89131
"\n",
90-
"Here is the list of currently supported execution options.\n",
91-
"\n",
92-
"```\n",
93-
"--debug: prints the q backtrace before raising a QError\n",
94-
" if the cell errors\n",
95-
"--display: calls display rather than the default print\n",
96-
" on returned objects\n",
97-
"```\n"
132+
"| **Execution option** | **Description** |\n",
133+
"|---------------|----------------------------------------------------|\n",
134+
"| --debug | Prints the q backtrace before raising a QError if the cell gives an error.|\n",
135+
"| --display | Calls display rather than the default print on returned objects.|"
98136
]
99137
},
100138
{
101139
"cell_type": "code",
102140
"execution_count": null,
141+
"id": "f9ed8310",
103142
"metadata": {},
104143
"outputs": [],
105144
"source": [
@@ -110,6 +149,7 @@
110149
{
111150
"cell_type": "code",
112151
"execution_count": null,
152+
"id": "daa9a196",
113153
"metadata": {},
114154
"outputs": [],
115155
"source": [
@@ -119,156 +159,155 @@
119159
},
120160
{
121161
"cell_type": "markdown",
122-
"id": "89ec26e4",
162+
"id": "2905895e",
123163
"metadata": {},
124164
"source": [
125-
"#### Executing against an external q process over IPC\n",
165+
"## 4. SQL interface\n",
126166
"\n",
127-
"Connection information can also be included after the `%%q` to connect to a remote `q` process over\n",
128-
"IPC.\n",
167+
"The `s)` syntax runs SQL queries against local tables within the `q` process.\n",
129168
"\n",
130-
"Here is the list of currently supported connection parameters.\n",
131-
"If they specify a type a second value is expected to follow them to be used as the parameter.\n",
132-
"If no type follows them they can be used as a stand alone flag.\n",
133-
"\n",
134-
"```\n",
135-
"--host: A string object denoting the host to connect to\n",
136-
"--port: An int object denoting the port to connect over\n",
137-
"--user: A str object denoting the username to use when connecting\n",
138-
"--password: A str object denoting the password to use when connecting\n",
139-
"--timeout: A float object denoting the time in seconds before the query\n",
140-
" times out, defaults to no timeout\n",
141-
"--nolarge: Disable messages over 2GB being sent / received\n",
142-
"--tls: Use a tls connection\n",
143-
"--unix: Use a unix connection\n",
144-
"--reconnection_attempts: An int object denoting how many\n",
145-
" reconnection attempts to make\n",
146-
"--noctx: Disable the context interface\n",
147-
"```\n",
148-
"\n",
149-
"Connect to a q server running on `localhost` at port `5001` as `user` using password `password`\n",
150-
"and disable the context interface."
169+
"Note: To use the SQL interface, first you need to load the `s.k_` library."
151170
]
152171
},
153172
{
154173
"cell_type": "code",
155174
"execution_count": null,
156-
"id": "1faca1e1",
157-
"metadata": {},
175+
"id": "56220bb5",
176+
"metadata": {
177+
"scrolled": true
178+
},
158179
"outputs": [],
159180
"source": [
160-
"%%q --host localhost --port 5000 --user user --pass password --noctx\n",
161-
"til 10"
181+
"%%q\n",
182+
"\\l s.k_\n",
183+
"tab:([]a:1000?1000; b:1000?500.0; c:1000?`AAPL`MSFT`GOOG);\n",
184+
"s) select * from tab where a>500 and b<250.0 limit 5"
162185
]
163186
},
164187
{
165188
"cell_type": "markdown",
166-
"id": "f046ebb6",
189+
"id": "da906296",
167190
"metadata": {},
168191
"source": [
169-
"All connection arguments are optional with the exception of the `--port` argument. If `--host` is not provided `localhost` will be used as the default host."
192+
"## 5. q namespaces\n",
193+
"\n",
194+
"You can use `q` namespaces, and switch between them with `\\d`.\n",
195+
"\n",
196+
"Note: The namespace is reset back to the base namespace `.` between cells."
170197
]
171198
},
172199
{
173200
"cell_type": "code",
174201
"execution_count": null,
175-
"id": "615d7d2e",
202+
"id": "502af937",
176203
"metadata": {},
177204
"outputs": [],
178205
"source": [
179-
"%%q --port 5000\n",
180-
"tab:([]a:1000?1000; b:1000?500.0; c:1000?`AAPL`MSFT`GOOG);"
181-
]
182-
},
183-
{
184-
"cell_type": "markdown",
185-
"id": "d756f342",
186-
"metadata": {},
187-
"source": [
188-
"It is possible to execute `q` code spanning multiple lines."
206+
"%%q\n",
207+
"\\d .example\n",
208+
"f: {[x] til x};"
189209
]
190210
},
191211
{
192212
"cell_type": "code",
193213
"execution_count": null,
194-
"id": "c739a80a",
195-
"metadata": {
196-
"scrolled": true
197-
},
214+
"id": "58d0c7c9",
215+
"metadata": {},
198216
"outputs": [],
199217
"source": [
200-
"%%q --port 5000\n",
201-
"afunc: {[x; y]\n",
202-
" x + y \n",
203-
" };\n",
204-
"afunc[0; 1]\n",
205-
"afunc[2; 3]"
218+
"%%q\n",
219+
"\\d\n",
220+
".example.f[10]"
206221
]
207222
},
208223
{
209224
"cell_type": "markdown",
210-
"id": "2905895e",
225+
"id": "52ca850e",
211226
"metadata": {},
212227
"source": [
213-
"#### Using the SQL interface\n",
214-
"The `s)` syntax to run SQL queries against local tables within the `q` process.\n",
228+
"## 6. (Advanced) q over IPC\n",
229+
"\n",
230+
"After `%%q` you can include connection information, if you wish to connect to a remote `q` process over IPC. \n",
215231
"\n",
216-
"Note: The `s.k_` library must be loaded first to use the SQL interface"
232+
"The list of supported connection parameters is below. The rule is:\n",
233+
"\n",
234+
"- If they have a type, it must be followed by a second value/parameter.\n",
235+
"- If there's no type after them, you can use them as a standalone flag.\n",
236+
"\n",
237+
"| **Parameter** &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;| **Object type and description**|\n",
238+
"|-----------------------|-----------------------------------------------|\n",
239+
"|--host | (string) The host to connect to. |\n",
240+
"|--port | (integer) The port to connect over. |\n",
241+
"|--user | (string) The username to use when connecting. |\n",
242+
"|--password | (string) The password to use when connecting. |\n",
243+
"|--timeout | (float) The time in seconds before the query times out. Defaults to no timeout.|\n",
244+
"|--nolarge | Disable messages over 2GB being sent / received. |\n",
245+
"|--tls | Use a tls connection. |\n",
246+
"|--unix | Use a unix connection. |\n",
247+
"|--reconnection_attempts| (integer) How many reconnection attempts to make.|\n",
248+
"|--noctx | Disable the context interface. |\n",
249+
"\n",
250+
"Connect to a q server running on `localhost` at port `5000` as `user` using password `password`\n",
251+
"and disable the context interface."
217252
]
218253
},
219254
{
220255
"cell_type": "code",
221256
"execution_count": null,
222-
"id": "56220bb5",
223-
"metadata": {
224-
"scrolled": true
225-
},
257+
"id": "a282e069",
258+
"metadata": {},
226259
"outputs": [],
227260
"source": [
228-
"%%q --port 5000\n",
229-
"\\l s.k_\n",
230-
"s) select * from tab where a>500 and b<250.0 limit 5"
261+
"%%q --host localhost --port 5000 --user user --pass password --noctx\n",
262+
"til 10"
231263
]
232264
},
233265
{
234266
"cell_type": "markdown",
235-
"id": "da906296",
267+
"id": "a1fe3b8e",
236268
"metadata": {},
237269
"source": [
238-
"#### Using namespaces\n",
239-
"You can also use `q` namespaces, and switch between them using `\\d`.\n",
240-
"\n",
241-
"Note: The namespace is reset back to the base namespace `.` between cells."
270+
"All connection arguments are optional, except the `--port` argument. If `--host` is not provided `localhost` is the default host."
242271
]
243272
},
244273
{
245274
"cell_type": "code",
246275
"execution_count": null,
247-
"id": "502af937",
276+
"id": "18d8416b",
248277
"metadata": {},
249278
"outputs": [],
250279
"source": [
251280
"%%q --port 5000\n",
252-
"\\d .example\n",
253-
"f: {[x] til x};"
281+
"tab:([]a:1000?1000; b:1000?500.0; c:1000?`AAPL`MSFT`GOOG);"
282+
]
283+
},
284+
{
285+
"cell_type": "markdown",
286+
"id": "e143c382",
287+
"metadata": {},
288+
"source": [
289+
"Note that it's possible to execute `q` code spanning multiple lines:"
254290
]
255291
},
256292
{
257293
"cell_type": "code",
258294
"execution_count": null,
259-
"id": "58d0c7c9",
295+
"id": "ccb197e8",
260296
"metadata": {},
261297
"outputs": [],
262298
"source": [
263299
"%%q --port 5000\n",
264-
"\\d\n",
265-
".example.f[10]"
300+
"afunc: {[x; y]\n",
301+
" x + y \n",
302+
" };\n",
303+
"afunc[0; 1]\n",
304+
"afunc[2; 3]"
266305
]
267306
},
268307
{
269308
"cell_type": "code",
270309
"execution_count": null,
271-
"id": "334d0ac5",
310+
"id": "c12a7d38",
272311
"metadata": {},
273312
"outputs": [],
274313
"source": [

0 commit comments

Comments
 (0)