Select Layer By Date And Time (Crime Analysis and Safety)

Summary

Selects records based on date and time ranges or date properties, for example, single date, time range, time period, days of the week, month, or year.

Usage

  • The input must be a feature layer or table view.

  • The input must contain a date field. If the input does not contain a date field, use the Convert Time Field tool to generate a date field derived from dates formatted as text in a text field.

  • This tool performs a selection using all the selection criteria. If any part of the input date does not match the selection criteria, the feature or record will not be selected.

    All date selections are based on the time zone of your computer.

  • To use this tool in a model or script, use the Make Table View or Make Feature Layer tool to convert an input feature class to a table view or feature layer, respectively, before running this tool.

Parameters

LabelExplanationData Type
Input Rows

The data containing a date field to which the selection will be applied.

Table View; Feature Layer
Selection Type

Specifies how the selection will be applied and what will occur if a selection already exists.

  • New selection The resulting selection will replace the current selection. This is the default.
  • Add to the current selection The resulting selection will be added to the current selection if one exists. If no selection exists, this is the same as the new selection option.
  • Remove from the current selection The resulting selection will be removed from the current selection. If no selection exists, this option has no effect.
  • Select subset from the current selection The resulting selection will be combined with the current selection. Only records that are common to both remain selected.
String
Time Type

Specifies how date and time fields will be used to select records.

  • Single Time FieldRecords will be selected based on a single time field on the input feature.
  • Time Range FieldsRecords will be selected based on start and end time fields on the input feature.
String
Date Field
(Optional)

The date field from the input layer on which the selection will be based. This parameter is only active if the Time Type parameter is set to Single Time Field.

Field
Start Date Field
(Optional)

The start date field from the time range on which the selection will be based. This parameter is only active if the Time Type parameter is set to Time Range Fields .

Field
End Date Field
(Optional)

The end date field from the time range on which the selection will be based. This parameter is only active if the Time Type parameter is set to Time Range Fields.

Field
Selection Options
(Optional)

Specifies how date and time selections will be made.

  • DateThe selection will be by date.
  • TimeThe selection will be by time of day.
  • Day of weekThe selection will be by day of the week.
  • MonthThe selection will be by month.
  • YearThe selection will be by year.
String
Date Selection Type
(Optional)

Specifies whether records will be selected based on a date range, single date, recency period, or comparative time period.

This parameter is only active when the Selection Options parameter is set to Date.

  • By Date RangeRecords will be selected based on a start and end date range.
  • By Single DateRecords will be selected based on the a single specified date.
  • By RecencyRecords will be selected based on a time period in relation to the current date (system date and time), for example, within the last 14 days.
  • By Comparative Time PeriodRecords will be selected based on the time period immediately preceding a recent time period in relation to the current date (system date and time). For example, if the current date is January 29 and the time slice is 14 days, records occurring between January 1 and January 14 will be selected. This option can be used in combination with a subsequent By Recency (RECENCY in Python) selection to compare record counts between two adjacent time periods (for example, the two 14-day time periods of January 1–14 and January 15–28).
String
Date
(Optional)

The single date and time to be selected.

This parameter is only active when the Date Selection Type parameter is set to By Single Date.

Date
Start Date
(Optional)

The start date of the date range.

This parameter is only active when the Date Selection Type parameter is set to By Date Range.

Date
End Date
(Optional)

The end date of the date range.

This parameter is only active when the Date Selection Type parameter is set to By Date Range.

Date
Use Current System time as End Time
(Optional)

Specifies whether records from the current day (local system time) will be included in the selection if they exist in the recent time period.

  • Checked—Records from the current day will be included in the selection.
  • Unchecked—Records from the current day will not be included in the selection.

For example, the time slice specified is 14 days, the local system time is 5:00 p.m on January 15 when the tool runs, the recency time period includes all records between 5:00 p.m. on the date 14 days ago and 5:00 p.m. on the day the tool runs, and this parameter is checked. In this example, the selection will be January 1, 2017 5:00:00 PM to January 15, 2017 5:00:00 PM for the 14-day time slice. Using this same example with this parameter unchecked, the recent period uses the beginning of the current day as the end time (based on local system time). In this case, the selection will be January 1, 2017 12:00:00 AM to January 15, 12:00:00 AM for the 14-day time slice.

This parameter is only active when the Date Selection Type parameter is set to By Comparative Time Period or By Recency.

Boolean
Time Slice
(Optional)

The number of time units (minutes, hours, days, weeks, months, or years) defining the recent time period on which the selection will be based, for example, events within the last 14 days.

This parameter is only active when the Date Selection Type parameter is set to By Comparative Time Period or By Recency.

Time Unit
Start Time
(Optional)

The start time of the time range.

This parameter is only active when the Selection Options parameter is set to Time.

Date
End Time
(Optional)

The end time of the time range.

This parameter is only active when the Selection Options parameter is set to Time.

Date
Days of Week
(Optional)

Specifies the day or days of the week that will be used to select records.

This parameter is only active when the Selection Options parameter is set to Day of week.

  • MondayRecords occurring on Monday will be selected.
  • TuesdayRecords occurring on Tuesday will be selected.
  • WednesdayRecords occurring on Wednesday will be selected.
  • ThursdayRecords occurring on Thursday will be selected.
  • FridayRecords occurring on Friday will be selected.
  • SaturdayRecords occurring on Saturday will be selected.
  • SundayRecords occurring on Sunday will be selected.
String
Months
(Optional)

Specifies the month or months that will be used to select records.

This parameter is only active when the Selection Options parameter is set to Month.

  • JanuaryRecords occurring in January will be selected.
  • FebruaryRecords occurring in February will be selected.
  • MarchRecords occurring in March will be selected.
  • AprilRecords occurring in April will be selected.
  • MayRecords occurring in May will be selected.
  • JuneRecords occurring in June will be selected.
  • JulyRecords occurring in July will be selected.
  • AugustRecords occurring in August will be selected.
  • SeptemberRecords occurring in September will be selected.
  • OctoberRecords occurring in October will be selected.
  • NovemberRecords occurring in November will be selected.
  • DecemberRecords occurring in December will be selected.
String
Years
(Optional)

The year or years that will be used to select records.

This parameter is only active when the Selection Options parameter is set to Years.

Long

Derived Output

LabelExplanationData Type
Updated Layer or Table View

The updated inputs with selections applied.

Table View; Feature Layer
Row Count

The number of selected records.

Long

arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view, selection_type, time_type, {date_field}, {start_date_field}, {end_date_field}, {selection_options}, {date_selection_type}, {single_date}, {start_date}, {end_date}, {use_system_time}, {time_slice}, {start_time}, {end_time}, {days_of_week}, {months}, {years})
NameExplanationData Type
in_layer_or_view

The data containing a date field to which the selection will be applied.

Table View; Feature Layer
selection_type

Specifies how the selection will be applied and what will occur if a selection already exists.

  • NEW_SELECTION The resulting selection will replace the current selection. This is the default.
  • ADD_TO_SELECTION The resulting selection will be added to the current selection if one exists. If no selection exists, this is the same as the new selection option.
  • REMOVE_FROM_SELECTION The resulting selection will be removed from the current selection. If no selection exists, this option has no effect.
  • SUBSET_SELECTION The resulting selection will be combined with the current selection. Only records that are common to both remain selected.
String
time_type

Specifies how date and time fields will be used to select records.

  • SINGLE_TIME_FIELDRecords will be selected based on a single time field on the input feature.
  • TIME_RANGE_FIELDSRecords will be selected based on start and end time fields on the input feature.
String
date_field
(Optional)

The date field from the input layer on which the selection will be based. This parameter is only active if the time_type parameter is set to SINGLE_TIME_FIELD.

Field
start_date_field
(Optional)

The start date field from the time range on which the selection will be based. This parameter is only active if the time_type parameter is set to TIME_RANGE_FIELDS.

Field
end_date_field
(Optional)

The end date field from the time range on which the selection will be based. This parameter is only active if the time_type parameter is set to TIME_RANGE_FIELDS.

Field
selection_options
[selection_options,...]
(Optional)

Specifies how date and time selections will be made.

  • DATEThe selection will be by date.
  • TIMEThe selection will be by time of day.
  • DAY_OF_WEEKThe selection will be by day of the week.
  • MONTHThe selection will be by month.
  • YEARThe selection will be by year.
String
date_selection_type
(Optional)

Specifies whether records will be selected based on a date range, single date, recency period, or comparative time period.

This parameter is only active when the selection_options parameter is set to DATE.

  • DATE_RANGERecords will be selected based on a start and end date range.
  • SINGLE_DATERecords will be selected based on the a single specified date.
  • RECENCYRecords will be selected based on a time period in relation to the current date (system date and time), for example, within the last 14 days.
  • COMPARATIVERecords will be selected based on the time period immediately preceding a recent time period in relation to the current date (system date and time). For example, if the current date is January 29 and the time slice is 14 days, records occurring between January 1 and January 14 will be selected. This option can be used in combination with a subsequent By Recency (RECENCY in Python) selection to compare record counts between two adjacent time periods (for example, the two 14-day time periods of January 1–14 and January 15–28).
String
single_date
(Optional)

The single date and time to be selected.

This parameter is only active when the date_selection_type parameter is set to SINGLE_DATE.

Date
start_date
(Optional)

The start date of the date range.

This parameter is only active when the date_selection_type parameter is set to DATE_RANGE.

Date
end_date
(Optional)

The end date of the date range.

This parameter is only active when the date_selection_type parameter is set to DATE_RANGE.

Date
use_system_time
(Optional)

Specifies whether records from the current day (local system time) will be included in the selection if they exist in the recent time period.

  • SYSTEM_TIMERecords from the current day will be included in the selection.
  • NO_SYSTEM_TIMERecords from the current day will not be included in the selection. This is the default.

For example, the time slice specified is 14 days, the local system time is 5:00 p.m. on January 15 when the tool runs, the recency time period includes all records between 5:00 p.m. on the date 14 days ago and 5:00 p.m. on the day the tool runs, and SYSTEM_TIME is selected. In this example, the selection will be January 1, 2017 5:00:00 PM to January 15, 2017 5:00:00 PM. Using this same example with NO_SYSTEM_TIME selected, the recent period uses the beginning of the current day as the end time (based on local system time). In this case, the selection will be January 1, 2017 12:00:00 AM to January 15, 12:00:00 AM for the 14-day time slice.

This parameter is only active when the date_selection_type parameter is set to COMPARATIVE or RECENCY.

Boolean
time_slice
(Optional)

The number of time units (minutes, hours, days, weeks, months, or years) defining the recent time period on which the selection will be based, for example, events within the last 14 days.

This parameter is only active when the date_selection_type parameter is set to COMPARATIVE or RECENCY.

Time Unit
start_time
(Optional)

The start time of the time range.

This parameter is only active when the selection_options parameter is set to TIME.

Date
end_time
(Optional)

The end time of the time range.

This parameter is only active when the selection_options parameter is set to TIME.

Date
days_of_week
[days_of_week,...]
(Optional)

Specifies the day or days of the week that will be used to select records.

  • MONDAYRecords occurring on Monday will be selected.
  • TUESDAYRecords occurring on Tuesday will be selected.
  • WEDNESDAYRecords occurring on Wednesday will be selected.
  • THURSDAYRecords occurring on Thursday will be selected.
  • FRIDAYRecords occurring on Friday will be selected.
  • SATURDAYRecords occurring on Saturday will be selected.
  • SUNDAYRecords occurring on Sunday will be selected.

This parameter is only active when the selection_options parameter is set to DAY_OF_WEEK.

String
months
[months,...]
(Optional)

Specifies the month or months that will be used to select records.

  • JANUARYRecords occurring in January will be selected.
  • FEBRUARYRecords occurring in February will be selected.
  • MARCHRecords occurring in March will be selected.
  • APRILRecords occurring in April will be selected.
  • MAYRecords occurring in May will be selected.
  • JUNERecords occurring in June will be selected.
  • JULYRecords occurring in July will be selected.
  • AUGUSTRecords occurring in August will be selected.
  • SEPTEMBERRecords occurring in September will be selected.
  • OCTOBERRecords occurring in October will be selected.
  • NOVEMBERRecords occurring in November will be selected.
  • DECEMBERRecords occurring in December will be selected.

This parameter is only active when the selection_options parameter is set to MONTH.

String
years
[years,...]
(Optional)

The year or years that will be used to select records.

This parameter is only active when the selection_options parameter is set to YEAR.

Long

Derived Output

NameExplanationData Type
out_layer_or_view

The updated inputs with selections applied.

Table View; Feature Layer
count

The number of selected records.

Long

Code sample

SelectLayerByDateAndTime example 1 (Python window)

The following script demonstrates how to use the SelectLayerByDateAndTime function in immediate mode.

import arcpy
arcpy.env.workspace = r"C:/data/city_pd.gdb"

arcpy.ca.SelectLayerByDateAndTime("Crimes",
                                "NEW_SELECTION",
                                "SINGLE_TIME_FIELD",
                                "offendate",
                                None,
                                None,
                                "DATE",
                                "DATE_RANGE",
                                None,
                                "8/1/2018",
                                "8/31/2018")
SelectLayerByDateAndTime example 2 (stand-alone window)

The stand-alone script below is an example of how to use the SelectLayerByDateAndTime function in a script:

# Name: SelectLayerByDateAndTime.py
# Description: Select crimes that occurred in the past 28 days, from 9 PM to 1 PM, on the weekend, from the month of October to December,
#              in the year 2018, and show the selection count. Finally, make a selection based on all the queries above.

# Import script modules
import arcpy

# Set the workspace
arcpy.env.workspace = r"C:\data\city_pd.gdb"

# Convert Feature class to table view
arcpy.management.MakeTableView("Crimes", "Crimes_View")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="DATE",
                                                date_selection_type="RECENCY",
                                                time_slice="28 Days")

arcpy.AddMessage("Crimes that occurred in past 28 days: {}".format(str(count)))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="TIME",
                                                start_time="9:00 PM",
                                                end_time="1:00 AM")

arcpy.AddMessage("All crimes that occurred between 9PM and 1AM: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="DAY_OF_WEEK",
                                                days_of_week=["SATURDAY", "SUNDAY"])

arcpy.AddMessage("All crimes that occurred on the weekend: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="MONTH",
                                                months=["OCTOBER", "NOVEMBER", "DECEMBER"])

arcpy.AddMessage("All crimes that occurred October through December: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")


lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="YEAR",
                                                years=[2018])

arcpy.AddMessage("All crimes that occurred in the year 2018: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")


# Combine selection options for more detailed time queries
lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options=["TIME", "DAY_OF_WEEK", "MONTH","YEAR"],
                                                start_time="9:00 PM",
                                                end_time="1:00 AM",
                                                days_of_week=["SATURDAY", "SUNDAY"],
                                                months=["OCTOBER", "NOVEMBER", "DECEMBER"],
                                                years=[2018])

message = """All crimes that occurred in the year 2018 during the months
of October through November on the weekends from 9PM to 1AM: {}
""".format(count)

arcpy.AddMessage(message)
arcpy.management.SelectLayerByAttribute("Crimes_View", "CLEAR_SELECTION")

Environments

This tool does not use any geoprocessing environments.