Skip to content

Query Documentation

Jump to bottom
Luke Sonnet edited this page Jun 24, 2016 · 9 revisions

This documentation details the syntax and options available for querying the VoteView database either from the R package Rvoteview or from the VoteView website.

General Syntax

Queries generally take the following form:

fieldname:fieldquery

For example, if we wanted to search an index of all of the text fields, we could use:

alltext:iraq war

Everything following a field name and a colon will be passed as an argument for that field until a new field name (defined as text followed by a colon) is found). For example,

alltext:iraq war congress:110

will search for all bills that have a high score for "iraq" and "war" in the full text index and are in the 110th session of Congress. There are several different fields one can query. Each field has a type, and each type accepts a certaint kind of input. We document the different fields and different types below. Each field has some useful examples to get you started.

What fields are available?

The available query fields are:

Do I always need to use a field name?

No. It is possible to just put text at the beginning of a query. Otherwise, however, you always have to specify a field name. Any word that precedes the first field name will be passed to the full text index. Therefore the above example is identical to:

iraq war congress:110

Note, you cannot place alltext queries without the alltext field name unless they are the first words in the query. Therefore

congress:110 iraq war

would NOT work as the query parser would try to search for the "iraq war" congress, which makes no sense. Of course,

congress:110 alltext:iraq war

will work just fine. Please also note that if you put an exact search as the only query, then it will only search over the description field as doing a regular expression search over all text fields can be quite slow. Therefore,

"iraq war"

is identical to

description:"iraq war"

In the end, it is usually best to use field names if you want to make sure your search is the right one.

How are the different fields joined together?

Fields are implicitly joined by AND statements. We can explicitly join fields by AND and OR statements. For example, if we wanted bills on Iraq in the 110th Congress or the 111th session of the House, we could use the following:

alltext:iraq (congress:110 OR (congress:111 AND chamber:House))

Lastly, anything contained in square brackets is passed literally through the parser.

Query Fields

alltext

  • Field type: Flex String
  • Description: The alltext field can be queried in two ways. If your query does not include quotation marks, then the words in the query field will be shortened and simplified and will be used as keywords to find the most relevant bills. This is likely the best option for most users. More precisely, the query searches a stemmed and lemmatized dictionary of all of the text associated with a bill. It then scores each bill and returns the bills that have the best score. Alternatively, if your query includes quotation marks, then the exact phrase within quotes will be searched for in any of the text fields in the database. This exact search is case-insensitive. Furthermore, it does not care whether the phrase is surrounded by whitespace, end of beginning of lines, or other text; it simply looks for that sequence of characters anywhere in the text fields. The current fields in the data that are included in this search are description, shortdescription, and codes.
  • Examples: alltext:iraq war, alltext:"iraq war", alltext:estate death sales tax

description

  • Field type: Flex String
  • Description: This field contains the most text for many of the bills. Although not drawn from a uniform source (mostly Congressional Quarterly), often the best place besides alltext to find many key words about a bill. If searched without quotes, it actually hits the Full Text index.
  • Examples: description:"affordable care act", description:dont ask dont tell

shortdescription

  • Field type: Flex String
  • Description: A shorter version of description. Not normally the best to search because it can be less informative. However, it can sometimes be easier to read this field in the returned data. If searched without quotes, it actually hits the Full Text index.
  • Examples: shortdescription:"slavery", shortdescription:"hate crimes", shortdescription:slavery emancipation abolish

codes

  • Field type: String
  • Description: This field contains the three types of codes listed below: Clausen, Peltzman, and Specific Issue codes. These are categories that can be searched to return a specific kind of roll call. This field allows you to simultaneously search over all three fields. Details about these codes can be found here. Furthermore, Poole and Rosenthal's 2007 book, Ideology and Congress details the construction of these codes and uses them in several analyses.
  • Examples: codes:defense, codes:Regulation OR codes:domestic

code.Clausen

  • Field type: String
  • Description: The Clausen codes are derived from the five categories described by Aage Clausen in his 1973 book "How Congressmen Decide: A Policy Focus" (in addition to a miscellaneous category added by Poole and Rosenthal). Roll calls may have one or two Clausen codes.Details about these codes can be found here.
  • Examples: code.Clausen:Civil Liberties, code.Clausen:civil liberties or code.Clausen:defense

code.Peltzman

  • Field type: String
  • Description: The Peltzman codes are derived from categories described in Peltzman (1984). Roll calls may have one or two Peltzman codes. Details about these codes can be found here.
  • Examples: code.Peltzman:Defense Policy, code.Peltzman:foreign OR code.Peltzman:defense

code.Issue

  • Field type: String
  • Description: The specific issue codes were built and presented in Poole and Rosenthal's 2007 book, Ideology and Congress. A full list of these codes can be found here.
  • Examples: code.Issue:Regulation, code.Issue:Union Regulation/Davis-Bacon/Situs Picketing

bill

  • Field type: String
  • Description: Bill names such as "H.R. 3590". This field is incomplete but may be useful for finding a precise roll call in later congresses.
  • Examples: bill:H.R. 3590, bill:3590

dates

  • Field type: Date
  • Description: This field contains the dates rollcalls were held on. They either can be searched exactly or using a range. To search for exact dates, just include the date in YYYY-MM-DD format or in YYYY format. Whenever you search YYYY, you are searching for all dates within that year. To search several specific dates at the same time you can just separate dates by white space. To search over a range, you can use [YYYY-MM-DD to YYYY-MM-DD].
  • Examples: dates:2014, dates:2013-03-04 2014-11-9, dates:[2010 to 2014-05-05]

startdate

  • Field type: Date
  • Description: This field can be used to set a start date for all roll calls. The query will return all roll calls after or on this date. Only takes a single date of format YYYY-MM-DD. Again, queries that are just YYYY will be treated as if they were YYYY-01-01 and will include all votes from that year.
  • Examples: startdate:2014, startdate:2013-04-09

enddate

  • Field type: Date
  • Description: This field can be used to set a end date for all roll calls. The query will return all roll calls before or on this date. Only takes a single date of format YYYY-MM-DD. Queries that are just YYYY will be treated as if they were the day of the following year. Thus if you search enddate:1810, the query will return all votes in 1810 or before. Thus searching enddate:1810 is equivalent to searching enddate:1811-01-01.
  • Examples: enddate:1833, enddate:1834-10-27

congress

  • Field type: Integer
  • Description: This field is the session of congress the roll call was held in.
  • Examples: congress:110, congress:100 104 106 90, congress:[90 to 94]

yea

  • Field type: Integer
  • Description: This field is the number of yea votes on a roll call. May be useful to find an exact bill that you know the yea count for.
  • Examples: yea:30, yea:30 31 35, yea:[10 to 90] congress:112 chamber:Senate

nay

  • Field type: Integer
  • Description: This field is the number of nay votes on a roll call. May be useful to find an exact bill that you know the nay count for.
  • Examples: nay:30, nay:30 31 35, (nay:[0 to 9] OR nay:[91 to 100]) congress:112 chamber:Senate

support

  • Field type: Integer
  • Description: This field is the percentage of total yea and nay votes that were yea for a rollcall. Precisely, (support = yea / (yea + nay)).
  • Examples: support:[15 to 85]

chamber

  • Field type: Chamber
  • Description: This field denotes whether the vote was in the House of Representatives or in the Senate.
  • Examples: chamber:House congress:110, chamber:Senate congress:10

voter

  • Field type: Voter
  • Description: This field contains the full list of voters who voted on a bill. The ID used is the internal member ID we have assigned to each unique legislator-congress-party. These numbers will be made available through a member API that is forthcoming. Warning, this can be quite slow for now.
  • Examples: voter:MS09819035

saved

  • Field type: saved
  • Description: This field contains any saved stashes of roll calls that users have created. Using the web interface, users can store batches of votes for use later. It may be convenient to create a set of votes using the web interface, stash them with an ID you create, and then download them in the R package.
  • Examples: saved:lukesavedvotes

Field Types

Flex String

  • Corresponding fields: alltext, description, shortdescription
  • Description: Flex string fields are treated as strings or as full text queries depending on whether there are any quotes (string literals) in the field query. If there are quotes, then the flex string is treated as a String; if there are no quotes, then the flex string is treated as a Full Text field and actually searches all text fields.

Full Text

  • Corresponding fields: alltext, description, shortdescription
  • Description: Full text field queries hit the full text index that is built on a stemmed and lemmatized dictionary of all of the text fields for each roll call. All bills are scored based on how relevant they are to the key words in a full text query and those above a threshold are returned. This means that a description query that has no quotes and is treated as a Full Text field actually searches all text fields rather than just the description field. This is done for speed and simplicity.

String

  • Corresponding fields: codes, code.Clausen, code.Peltzman, code.Issue, bill, alltext, description, shortdescription
  • Description: String fields are queried using a case-insensitve exact match for the phrase in the related field. The regular expression looks for that exact sequence of characters which may be bookeneded by whitespace, the end of the string, or other characters. Thus if you are searching for "emancipation", "mancipati" will return at least the same bills as "emancipation" if not more. Note that quotes are unnecessary for string fields as all searches are treated as string literals.

Date

  • Corresponding fields: dates, startdate, enddate
  • Description: Date fields can be queried using either the YYYY or the YYYY-MM-DD syntax. Generally, YYYY is always replaced with YYYY-01-01, although if it is used in enddate, it is treated as January 1st of the following year.

Integer

  • Corresponding fields: congress, yea, nay, support
  • Description: Integer fields can be queried in three different ways. If the query is just a number, then the query returns roll calls that are an exact match for that field (e.g. congress:110). If the query is a list of numbers separated by white space, then the query returns roll calls that are an exact match for any of the numbers in the list for that field (e.g. yea: 10 11 15). If the query is for a range of numbers, the preferred format is like so [lownumber to highnumber] (e.g. support:[15 to 85]).

Chamber

  • Corresponding fields: chamber
  • Description: The chamber field only accepts either "House" or "Senate" and is case-insensitive.

Voter

  • Corresponding fields: voter
  • Description: The voter field only accepts exact matches with the internal ID that is unique to the legislator-party-congress.

Saved

  • Corresponding fields: saved
  • Description: The saved field only accepts exact matches with the ID that users assign to collections of roll calls.

Clone this wiki locally