Skip to content
Navigation Menu
{{ message }}
forked from apache/cassandra-python-driver
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathuser_defined_types.html
More file actions
216 lines (176 loc) · 16.1 KB
/
Copy pathuser_defined_types.html
File metadata and controls
216 lines (176 loc) · 16.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="refresh" content="0; URL=https://docs.datastax.com/en/developer/python-driver/latest/user_defined_types/">
<link rel="canonical" href="https://docs.datastax.com/en/developer/python-driver/latest/user_defined_types/">
<title>User Defined Types — Cassandra Driver 3.13.0 documentation</title>
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.13.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Object Mapper" href="object_mapper.html" />
<link rel="prev" title="Security" href="security.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="user-defined-types">
<span id="udts"></span><h1>User Defined Types<a class="headerlink" href="#user-defined-types" title="Permalink to this headline">¶</a></h1>
<p>Cassandra 2.1 introduced user-defined types (UDTs). You can create a
new type through <code class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TYPE</span></code> statements in CQL:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">CREATE</span> <span class="n">TYPE</span> <span class="n">address</span> <span class="p">(</span><span class="n">street</span> <span class="n">text</span><span class="p">,</span> <span class="nb">zip</span> <span class="nb">int</span><span class="p">);</span>
</pre></div>
</div>
<p>Version 2.1 of the Python driver adds support for user-defined types.</p>
<div class="section" id="registering-a-class-to-map-to-a-udt">
<h2>Registering a Class to Map to a UDT<a class="headerlink" href="#registering-a-class-to-map-to-a-udt" title="Permalink to this headline">¶</a></h2>
<p>You can tell the Python driver to return columns of a specific UDT as
instances of a class by registering them with your <a class="reference internal" href="api/cassandra/cluster.html#cassandra.cluster.Cluster" title="cassandra.cluster.Cluster"><code class="xref py py-class docutils literal"><span class="pre">Cluster</span></code></a>
instance through <a class="reference internal" href="api/cassandra/cluster.html#cassandra.cluster.Cluster.register_user_type" title="cassandra.cluster.Cluster.register_user_type"><code class="xref py py-meth docutils literal"><span class="pre">Cluster.register_user_type()</span></code></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">cluster</span> <span class="o">=</span> <span class="n">Cluster</span><span class="p">(</span><span class="n">protocol_version</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="n">session</span> <span class="o">=</span> <span class="n">cluster</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span>
<span class="n">session</span><span class="o">.</span><span class="n">set_keyspace</span><span class="p">(</span><span class="s1">'mykeyspace'</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"CREATE TYPE address (street text, zipcode int)"</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"CREATE TABLE users (id int PRIMARY KEY, location frozen<address>)"</span><span class="p">)</span>
<span class="c1"># create a class to map to the "address" UDT</span>
<span class="k">class</span> <span class="nc">Address</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">street</span><span class="p">,</span> <span class="n">zipcode</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">street</span> <span class="o">=</span> <span class="n">street</span>
<span class="bp">self</span><span class="o">.</span><span class="n">zipcode</span> <span class="o">=</span> <span class="n">zipcode</span>
<span class="n">cluster</span><span class="o">.</span><span class="n">register_user_type</span><span class="p">(</span><span class="s1">'mykeyspace'</span><span class="p">,</span> <span class="s1">'address'</span><span class="p">,</span> <span class="n">Address</span><span class="p">)</span>
<span class="c1"># insert a row using an instance of Address</span>
<span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"INSERT INTO users (id, location) VALUES (</span><span class="si">%s</span><span class="s2">, </span><span class="si">%s</span><span class="s2">)"</span><span class="p">,</span>
<span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">Address</span><span class="p">(</span><span class="s2">"123 Main St."</span><span class="p">,</span> <span class="mi">78723</span><span class="p">)))</span>
<span class="c1"># results will include Address instances</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"SELECT * FROM users"</span><span class="p">)</span>
<span class="n">row</span> <span class="o">=</span> <span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="k">print</span> <span class="n">row</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">row</span><span class="o">.</span><span class="n">location</span><span class="o">.</span><span class="n">street</span><span class="p">,</span> <span class="n">row</span><span class="o">.</span><span class="n">location</span><span class="o">.</span><span class="n">zipcode</span>
</pre></div>
</div>
</div>
<div class="section" id="using-udts-without-registering-them">
<h2>Using UDTs Without Registering Them<a class="headerlink" href="#using-udts-without-registering-them" title="Permalink to this headline">¶</a></h2>
<p>Although it is recommended to register your types with
<a class="reference internal" href="api/cassandra/cluster.html#cassandra.cluster.Cluster.register_user_type" title="cassandra.cluster.Cluster.register_user_type"><code class="xref py py-meth docutils literal"><span class="pre">Cluster.register_user_type()</span></code></a>, the driver gives you some options
for working with unregistered UDTS.</p>
<p>When you use prepared statements, the driver knows what data types to
expect for each placeholder. This allows you to pass any object you
want for a UDT, as long as it has attributes that match the field names
for the UDT:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">cluster</span> <span class="o">=</span> <span class="n">Cluster</span><span class="p">(</span><span class="n">protocol_version</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="n">session</span> <span class="o">=</span> <span class="n">cluster</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span>
<span class="n">session</span><span class="o">.</span><span class="n">set_keyspace</span><span class="p">(</span><span class="s1">'mykeyspace'</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"CREATE TYPE address (street text, zipcode int)"</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"CREATE TABLE users (id int PRIMARY KEY, location frozen<address>)"</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">street</span><span class="p">,</span> <span class="n">zipcode</span><span class="p">,</span> <span class="n">otherstuff</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">street</span> <span class="o">=</span> <span class="n">street</span>
<span class="bp">self</span><span class="o">.</span><span class="n">zipcode</span> <span class="o">=</span> <span class="n">zipcode</span>
<span class="bp">self</span><span class="o">.</span><span class="n">otherstuff</span> <span class="o">=</span> <span class="n">otherstuff</span>
<span class="n">insert_statement</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">prepare</span><span class="p">(</span><span class="s2">"INSERT INTO users (id, location) VALUES (?, ?)"</span><span class="p">)</span>
<span class="c1"># since we're using a prepared statement, we don't *have* to register</span>
<span class="c1"># a class to map to the UDT to insert data. The object just needs to have</span>
<span class="c1"># "street" and "zipcode" attributes (which Foo does):</span>
<span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">insert_statement</span><span class="p">,</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="n">Foo</span><span class="p">(</span><span class="s2">"123 Main St."</span><span class="p">,</span> <span class="mi">78723</span><span class="p">,</span> <span class="s2">"some other stuff"</span><span class="p">)])</span>
<span class="c1"># when we query data, UDT columns that don't have a class registered</span>
<span class="c1"># will be returned as namedtuples:</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"SELECT * FROM users"</span><span class="p">)</span>
<span class="n">first_row</span> <span class="o">=</span> <span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">address</span> <span class="o">=</span> <span class="n">first_row</span><span class="o">.</span><span class="n">location</span>
<span class="k">print</span> <span class="n">address</span> <span class="c1"># prints "Address(street='123 Main St.', zipcode=78723)"</span>
<span class="n">street</span> <span class="o">=</span> <span class="n">address</span><span class="o">.</span><span class="n">street</span>
<span class="n">zipcode</span> <span class="o">=</span> <span class="n">address</span><span class="o">.</span><span class="n">street</span>
</pre></div>
</div>
<p>As shown in the code example, inserting data for UDT columns without registering
a class works fine for prepared statements. However, <strong>you must register a
class to insert UDT columns with unprepared statements</strong>.* You can still query
UDT columns without registered classes using unprepared statements, they will
simply return <code class="docutils literal"><span class="pre">namedtuple</span></code> instances (just like prepared statements do).</p>
<p>* this applies to <em>parameterized</em> unprepared statements, in which the driver will be formatting parameters – not statements with interpolated UDT literals.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">Cassandra Driver</a></h1>
<p class="blurb">Python driver for Cassandra</p>
<p>
<iframe src="https://ghbtns.com/github-btn.html?user=datastax&repo=python-driver&type=star&count=true&size=large&v=2"
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>
<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="upgrading.html">Upgrading</a></li>
<li class="toctree-l1"><a class="reference internal" href="execution_profiles.html">Execution Profiles</a></li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="query_paging.html">Paging Large Queries</a></li>
<li class="toctree-l1"><a class="reference internal" href="lwt.html">Lightweight Transactions (Compare-and-set)</a></li>
<li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">User Defined Types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#registering-a-class-to-map-to-a-udt">Registering a Class to Map to a UDT</a></li>
<li class="toctree-l2"><a class="reference internal" href="#using-udts-without-registering-them">Using UDTs Without Registering Them</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="object_mapper.html">Object Mapper</a></li>
<li class="toctree-l1"><a class="reference internal" href="dates_and_times.html">Working with Dates and Times</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="security.html" title="previous chapter">Security</a></li>
<li>Next: <a href="object_mapper.html" title="next chapter">Object Mapper</a></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2013-2017 DataStax.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.6</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
|
<a href="_sources/user_defined_types.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
You can’t perform that action at this time.